Zo Computer Memory System — Quick Start Guide

For new Zo users who want Zo to remember things across conversations

Why would you want a memory system?

Without one, Zo starts every conversation cold — no memory of who you are, what you're working on, or what you've discussed before. You end up re-explaining yourself constantly.

A memory system fixes that. Zo reads your context at the start of every conversation, so you don't have to repeat yourself. The more you build it, the more useful it becomes.

This guide walks you through building a simple, file-based memory system by prompting Zo through chat. No code. No databases. Just text files that Zo reads and writes.

Part 1 — Core Concepts

Before you start building, it helps to understand what each piece does.

USER.md — Your profile

A single file that describes you. Zo reads this at the start of every conversation — your name, role, how you like to communicate, your preferences. Think of it as your personal README.

You own and edit this file. Zo never changes it on its own.

USER.md
  └── Your name, role, communication style, preferences

MEMORY.md — The index

The table of contents for everything Zo remembers. One line per memory entry, pointing to files inside the memory/ folder. Short by design — it grows only as memory entries grow.

This is maintained by Zo. You don't need to touch it directly, though you can edit it.

MEMORY.md
  └── One line per memory entry, with a link to the full file

memory/ — Where memories live

A folder that holds all your memory files. Each file covers one topic. Files are grouped into subfolders by type:

memory/
  ├── SYSTEM_CONFIG.md          ← Your editable config
  ├── jing-profile.md           ← type: user
  ├── projects/                 ← type: project
  │   └── example.md
  ├── feedback/                 ← type: feedback
  │   └── example.md
  └── daily/                    ← type: daily
      └── YYYY-MM-DD.md

Folder types:

Frontmatter — How memory files are structured

Every memory file starts with a block like this:

---
name: example-entry
description: One clear sentence about what this memory is
type: feedback
---

This is called frontmatter. It's metadata — structured information at the top of the file that Zo uses to understand and sort the entry. You don't need to write it yourself; Zo creates it automatically when it saves new memories.

Fields:

• name — a short slug (no spaces, lowercase) that identifies the entry
• description — one clear sentence about what this memory covers
• type — what kind of memory it is: user, project, feedback, or reference

SYSTEM_CONFIG.md — Your edit file (important)

This is the file you own and edit. It's separate from everything else Zo uses. It has two jobs:

1. Documents the current system — so you can see what exists
2. Records changes you want — put what you want changed in the "Your pending changes" section, and Zo will apply it

SYSTEM_CONFIG.md
  └── Your editable config. You edit this. Zo reads it.

How to use it: Edit the "Your pending changes" section at the bottom of the file. Write what you want changed in plain English. At the start of your next conversation, Zo will read it, apply the changes, and confirm what was done.

Rules — What makes it automatic

Rules are instructions that tell Zo when to do things automatically. Two rules run the memory system:

Rule 1 — At conversation start

At the start of every conversation, Zo reads USER.md and MEMORY.md for context.

Zo loads your profile and all your memory entries automatically. No prompting needed. Every new conversation starts with context.

Rule 2 — During conversation (proactive capture)

When you share a preference, correct Zo's approach, or describe an ongoing project, Zo saves it to memory automatically.

Additionally — and this is the key part — Zo will proactively ask if you want to save a session note when a conversation produces significant decisions, new context, or non-trivial work. It will say:

"Want me to save a note on this?"

If you say yes, Zo creates a dated daily note in memory/daily/ with a summary of what was discussed. If you say no, it moves on. No friction either way.

This means the system grows even if you don't remember to ask — Zo prompts you when it makes sense to capture something.

scripts/memory-search.py — How search works

When you ask Zo about a past topic that isn't in MEMORY.md (e.g., "what did we talk about with the client last week?"), Zo runs a grep-based search across all memory files to find relevant entries.

scripts/memory-search.py
  └── Grep-based keyword search across memory files

This is a simple text search, not a vector database. It works well up to a few hundred entries. If memory grows large, a database-backed search can be added later.

Part 2 — What Gets Created

Here's the complete file and folder structure that gets built:

/home/workspace/
├── USER.md                    ← Your profile (stub to start)
├── MEMORY.md                  ← Index of all memory entries
├── memory/
│   ├── SYSTEM_CONFIG.md       ← Your edit file (KEY FILE)
│   ├── jing-profile.md        ← Memory: who you are
│   ├── projects/              ← Project memories
│   │   └── example.md
│   ├── feedback/              ← Preference memories
│   │   └── example.md
│   └── daily/                 ← Daily conversation notes
│       └── YYYY-MM-DD.md
└── scripts/
    └── memory-search.py       ← Search helper script

What each file does:

USER.md           → Zo reads this to know who you are
MEMORY.md         → Zo reads this to know what it already remembers
memory/SYSTEM_CONFIG.md → You edit this to change the system
memory/*/        → Individual memory files by topic
scripts/memory-search.py → Tool Zo uses to search memories

Part 3 — The Prompts to Send Zo

You can copy and paste these prompts into a Zo conversation. Each prompt is designed to do one step.

Step 1 — Tell Zo about yourself

Send Zo this prompt (edit the parts in brackets):

I want you to build me a memory system. Here's some information about me:
- My name is [YOUR NAME]
- I am a [YOUR ROLE]
- I like to communicate [how you like to communicate — e.g., "concisely, with short answers"]
- [Any other preferences or context you want Zo to know]

Create and fill in /home/workspace/USER.md with this information.
Then add a one-line entry for it in MEMORY.md.
Confirm when done.

Step 2 — Set up the folder structure

Send this prompt:

Create the following folder structure in /home/workspace/memory/:
- memory/daily/
- memory/projects/
- memory/feedback/
- memory/reference/
- scripts/

Create the following files as stubs:
- memory/SYSTEM_CONFIG.md — an editable config file I can use to modify the memory system
- memory/daily/YYYY-MM-DD.md — a daily note for today with stubs for what we worked on, decisions made, next steps, and notes
- scripts/memory-search.py — a grep-based search script that searches memory files by keyword

Confirm the folder structure and all files are created.

Step 3 — Register the two rules

Send this prompt:

Register two rules for the memory system:

Rule 1 (condition):
"At the start of every conversation, or when the user asks about past interactions, preferences, or prior decisions"

Rule 1 (instruction):
"Read /home/workspace/USER.md and /home/workspace/MEMORY.md for context. If the user references a topic that maps to an entry in MEMORY.md, also read the linked file. For 'what did we discuss recently?' style questions, list the 5 most recent files in /home/workspace/memory/daily/ sorted by modification time and read the top one. If the user asks about a past topic that isn't in MEMORY.md, run python3 /home/workspace/scripts/memory-search.py <keywords> first."

Rule 2 (condition):
"When the user shares a new preference, corrects your approach, validates an unusual choice, describes ongoing project context, or references an external system"

Rule 2 (instruction):
"Create or update a file under /home/workspace/memory/ using the frontmatter schema. Add or update a one-line entry in MEMORY.md. Convert relative dates to absolute dates (e.g., 'next week' → '2026-05-06'). Before writing a new file, check if an existing one covers the topic and update that instead. Never duplicate. For feedback type: include 'Why:' and 'How to apply:' lines in the body.

Additionally: if a conversation produces significant decisions, new context, or non-trivial work — even if none of the above conditions fire — proactively offer to save a session note before the conversation ends or when the user goes quiet. Format: 'Want me to save a note on this?' If yes, create /home/workspace/memory/daily/YYYY-MM-DD.md with a one-line summary and key takeaways."

Confirm both rules are registered.

Step 4 — Set up SYSTEM_CONFIG.md as your edit file

Send this prompt:

Fill in /home/workspace/memory/SYSTEM_CONFIG.md with:
1. A section explaining what the file is and how to use it
2. A table documenting all operational files (USER.md, MEMORY.md, memory/, scripts/)
3. A section explaining the two rules and what they do
4. A "Your pending changes" section at the bottom with a reminder to edit it to request changes

Make it clear, simple, and useful for someone who has never used a memory system before.
Confirm when done.

Step 5 — Create a first memory entry

Send this prompt:

Create a memory entry at /home/workspace/memory/feedback/first-session.md using the frontmatter schema (name, description, type).
Set type to "feedback" or "reference".
In the body, describe that the user set up their memory system today, what was created, and why.
Add a one-line entry to MEMORY.md.
Confirm when done.

Step 6 — Write today's daily note

Send this prompt:

Fill in /home/workspace/memory/daily/YYYY-MM-DD.md (today's date) with:
- What we worked on
- What decisions were made
- What the next steps are
- Any notes from today's session

Use real content based on what we just built.
Add a one-line entry to MEMORY.md if not already present.
Confirm when done.

Part 4 — How the System Grows

How memories are created automatically

The system captures memories in two ways:

1. Reactive capture (automatic, no action needed) When you say something that matches Rule 2's condition — a preference, a project update, a correction — Zo creates a memory file without being asked.

You: "I only work with clients who pay upfront"
Zo: [silently creates memory/feedback/payment-preference.md]

2. Proactive offer (Zo asks, you decide) When a conversation ends with significant decisions or new context — but none of the reactive conditions fired — Zo will say:

Zo: "Want me to save a note on this?"
You: "Yes"
Zo: [creates memory/daily/2026-04-29.md with summary]

This means you don't have to remember to ask. Zo reminds you when it makes sense.

How to modify the system later

The system grows over time. Here are the common ways to change it:

To add a new type of memory folder

Edit SYSTEM_CONFIG.md → "Your pending changes" section:

I want to add a new memory folder type: memory/clients/
Use it for notes about clients I'm working with.
Please:
1. Create the folder
2. Add a section to SYSTEM_CONFIG.md documenting it
3. Update MEMORY.md with a note about it

To change how Zo responds to you

Edit SYSTEM_CONFIG.md → "Your pending changes" section:

I want Zo to always start responses with a one-line summary.
Please update USER.md or the relevant memory entry to reflect this preference.

To search past memories

Just ask Zo naturally:

What did we discuss about [topic]?

Zo will run the search script and read the results. You don't need to think about the mechanics.

To see what memories exist

Show me all my memory entries.

Zo will read MEMORY.md and summarize what's there.

Part 5 — The Two Rules in Plain English

Here's what the automation actually does, in simple terms:

Rule 1: At the start of every conversation

Zo automatically does this before it says hello:

1. Read USER.md     → Who is this person?
2. Read MEMORY.md   → What do I already know about them?
3. Check daily/     → What did we talk about recently?
4. Ready to help    → Can start the conversation with context

You don't have to ask for this. It happens automatically.

Rule 2: During conversation

Zo does two things under this rule:

A. Reactive capture — saves without asking when you:

• Share a new preference
• Correct Zo's approach
• Describe an ongoing project
• Reference an external system

You say: "I only work with clients who pay upfront"
Zo saves: memory/feedback/payment-preference.md
         (type: feedback, with Why + How to Apply)
         Then updates MEMORY.md with a one-line entry

B. Proactive offer — asks if you want to save when: A conversation ends (or goes quiet) with significant decisions, new context, or non-trivial work, even if none of the reactive conditions fired.

[Conversation about a new project ends]
Zo: "Want me to save a note on this?"
You: "Yes"
Zo: Creates memory/daily/YYYY-MM-DD.md with a summary

You say yes or no. Zo acts on your answer. No friction.

Part 6 — Troubleshooting

Summary

What you build          → A file-based memory system
What you get            → Zo knows who you are across every conversation
What you maintain       → SYSTEM_CONFIG.md (your edit file)
What Zo maintains       → MEMORY.md, memory files, daily notes
How it grows            → Automatically when you share preferences or
                         projects; Zo proactively asks to save notes
How to change it        → Edit SYSTEM_CONFIG.md, ask Zo to apply changes

Start with Step 1. Add steps as you go. The system builds itself through conversation.