Memory

Memory lets Nyzhi remember things across sessions. Preferences, project conventions, architectural decisions, debugging notes — anything you’d normally repeat can be stored and automatically recalled.

Two Memory Scopes

User memory follows you across all projects. Project memory is scoped to a single codebase.

How It Works

1. Auto-injection — when auto_memory is enabled (default), Nyzhi loads relevant memory into the system prompt at the start of each session
2. On-demand writing — the agent saves new knowledge using memory_write during a session
3. Topic-based organization — memory is organized into named topics (each a separate .md file)
4. Index tracking — MEMORY.md maintains a linked index of all topics

Reading Memory

From the Agent

The agent can read memory at any time:

memory_read()                    # returns the memory index
memory_read(topic: "api-design") # returns a specific topic

From the File System

Memory is just markdown files — you can read and edit them directly:

# User memory
cat ~/.nyzhi/MEMORY.md

# Project memory
ls ~/.local/share/nyzhi/projects/<hash>/memory/
cat ~/.local/share/nyzhi/projects/<hash>/memory/api-design.md

The project hash is a SHA-256 of the canonical project root path (first 8 bytes, hex-encoded).

Writing Memory

The agent writes memory using memory_write:

memory_write(topic: "conventions", content: "Always use kebab-case for file names")

Write modes:

Writing a topic automatically updates the MEMORY.md index with a link to the topic file.

Prompt Injection

When auto_memory is enabled, Nyzhi loads memory into the system prompt:

• User memory gets up to half the line budget
• Project memory gets the remaining budget
• Total cap: 200 lines

This keeps memory useful without consuming too much context window.

Configuration

[memory]
auto_memory = true    # automatically load and save memory (default: true)

To disable:

[memory]
auto_memory = false

Note: auto_memory uses OR merge semantics — if either global or project config enables it, it’s enabled.

Managing Memory

Clear Project Memory

From the TUI:

/memory clear

Or delete the files directly:

rm -rf ~/.local/share/nyzhi/projects/<hash>/memory/

View Memory Index

memory_read()

Returns the contents of MEMORY.md with links to all topic files.

List Topics

memory_read()

The index shows all available topics.

Subagent Context Briefing

When a subagent is spawned, it can receive a context briefing that includes a project memory excerpt. This is controlled by SharedContext::build_briefing():

• Total briefing: up to 60 lines
• Recent changes: up to 20 entries
• Message preview: up to 5 messages

This ensures subagents have enough context without overwhelming their prompt.

Examples

Saving Project Conventions

"Remember that we use PostgreSQL for the database and Redis for caching"

The agent saves this to memory, and it’s available in future sessions.

Saving Debugging Knowledge

"Remember that the auth timeout issue was caused by clock skew between services"

Next time a similar issue comes up, the agent already knows the root cause.

Saving API Design Decisions

"Save to memory: API responses always use envelope format { data, meta, error }"

Best Practices

• Keep entries concise — memory is injected into prompts, so brevity matters
• Use topics — organize knowledge by domain (conventions, decisions, debugging)
• Clear stale memory — run /memory clear when a project’s context changes significantly
• Use project memory for project-specific things, user memory for personal preferences
• Review periodically — memory files are plain markdown, read them to check for outdated info

Next Steps

• Skills — reusable instruction packs
• Configuration — memory config reference
• Sessions — conversation history