Skip to main content

​
Quick start

This guide walks you through saving your first memory and seeing how your agent uses it in future sessions.
If you haven’t installed EchoVault yet, start with the installation guide.

​
Save your first memory

Let’s say you just made a decision to switch from session cookies to JWT authentication. Save this for future sessions: 
memory save \
  --title "Switched to JWT auth" \
  --what "Replaced session cookies with JWT" \
  --why "Needed stateless auth for API" \
  --impact "All endpoints now require Bearer token" \
  --tags "auth,jwt" \
  --category "decision" \
  --details "Context:
We had session cookies tied to server state. API clients needed auth without cookies.

Options considered:
- Keep session cookies (requires sticky sessions)
- Move to JWT (stateless, works everywhere)

Decision:
JWT with 1h expiry, refresh tokens for long-lived sessions.

Tradeoffs:
- Pro: stateless, scales horizontally
- Con: can't revoke tokens until expiry

Follow-up:
Implement refresh token rotation for security."
You’ll see: 
Saved: Switched to JWT auth (id: 20260301a1b2)
File: ~/.memory/vault/my-project/2026-03-01-session.md
Use --details-file notes.md to load details from a file, or --details-template to scaffold a structured template automatically.

​
How agents use memory

Once set up, your agent uses memory via MCP tools:
1

Session start

The agent calls memory_context to load prior decisions and context for the current project.
{
  "total": 5,
  "showing": 5,
  "memories": [
    {
      "id": "20260301a1b2",
      "title": "Switched to JWT auth",
      "category": "decision",
      "tags": ["auth", "jwt"],
      "date": "Mar 01"
    }
  ],
  "message": "Use memory_search for specific topics. IMPORTANT: You MUST call memory_save before this session ends if you make any changes, decisions, or discoveries."
}
The agent now knows about your JWT decision before doing any work.
2

During work

When working on related topics, the agent calls memory_search to find relevant memories:
// Agent searches: "authentication"
[
  {
    "id": "20260301a1b2",
    "title": "Switched to JWT auth",
    "what": "Replaced session cookies with JWT",
    "why": "Needed stateless auth for API",
    "impact": "All endpoints now require Bearer token",
    "category": "decision",
    "tags": ["auth", "jwt"],
    "project": "my-project",
    "created_at": "2026-03-01",
    "score": 0.95,
    "has_details": true
  }
]
The agent can fetch full details if needed using the memory ID.
3

Session end

When the agent makes changes, fixes bugs, or learns something, it calls memory_save to persist the knowledge:
{
  "title": "Implement refresh token rotation",
  "what": "Added refresh token rotation to prevent token reuse attacks",
  "why": "Follow-up from JWT auth decision",
  "category": "learning",
  "tags": ["auth", "security", "jwt"]
}
This memory is now available for the next session.
The MCP tool descriptions instruct agents to save and retrieve automatically. In most cases, no manual prompting is needed. However, you can always use the CLI directly for manual memory management.

​
Search memories from the CLI

You don’t need to wait for your agent. Search memories directly: 
memory search "authentication"
Output: 
Results (1 found)

[1] Switched to JWT auth (score: 0.95)
    decision | 2026-03-01 | my-project
    What: Replaced session cookies with JWT
    Why: Needed stateless auth for API
    Impact: All endpoints now require Bearer token
    Details: available (use `memory details 20260301a1b2`)
Get full details: 
memory details 20260301a1b2

​
View project context

See all memories for your current project: 
memory context --project
Output: 
Available memories (5 total, showing 5):
- [Mar 01] Switched to JWT auth [decision] [auth,jwt]
- [Feb 28] Fixed CORS preflight issue [bug] [api,cors]
- [Feb 27] Setup PostgreSQL connection pooling [context] [database]
- [Feb 26] Implement rate limiting [pattern] [api,security]
- [Feb 25] Project kickoff [context]
Use `memory search <query>` for full details on any memory.

​
Memory categories

Use categories to organize memories by type:
  • decision — Chose X over Y (architectural, design, technical choices)
  • bug — Fixed a problem (include root cause and solution)
  • pattern — Reusable gotcha or best practice discovered
  • learning — Non-obvious discovery about the codebase or tools
  • context — Project setup, infrastructure, or background information

​
When to save memories

Save when you:
  • Made an architectural or design decision
  • Fixed a bug (include root cause and solution)
  • Discovered a non-obvious pattern or gotcha
  • Learned something about the codebase not obvious from code
  • Set up infrastructure, tooling, or configuration
  • The user corrected you or clarified a requirement
Do not save:
  • Trivial changes (typos, formatting)
  • Information obvious from reading the code
  • Duplicates of existing memories
Write memories for a future agent with zero context. Include the “why” and “what changed” — not just the “what”.

​
List sessions

See all session files across projects: 
memory sessions
Output: 
Sessions:
  2026-03-01 | my-project
  2026-02-28 | my-project
  2026-02-27 | my-project
  2026-02-15 | other-project
Session files are Obsidian-compatible Markdown stored in ~/.memory/vault/. You can open them in Obsidian or any text editor.

​
Delete a memory

Remove a memory by ID or prefix: 
memory delete 20260301a1b2

​
View configuration

Check your current configuration: 
memory config
Output: 
embedding:
  provider: ollama
  model: nomic-embed-text
  base_url: http://localhost:11434
  api_key: null
enrichment:
  provider: none
context:
  semantic: auto
  topup_recent: true
memory_home: /home/user/.memory
memory_home_source: default
API keys are automatically redacted in config output for security.

​
Next steps

CLI reference

Complete command reference for all memory CLI commands

Configuration

Configure embeddings, storage location, and search behavior

Build docs developers (and LLMs) love

Get started for freeTalk to us