memobank

AI agents forget everything between sessions. Static files like CLAUDE.md go stale and require manual upkeep. Cloud memory APIs add external services your team doesn't own or control.

memobank gives AI agents persistent, structured memory that lives in your Git repo — versioned alongside code, reviewed as PRs, and loaded automatically at session start.

• Personal — private lessons and preferences, never committed
• Team — shared knowledge that travels with the codebase
• Workspace — cross-repo patterns, synced via a separate Git remote

Works with Claude Code, Cursor, Codex, Gemini CLI, and Qwen Code. Zero external services required.

Get started

npm install -g memobank-cli
cd your-project
memo onboarding  # creates .memobank/ and configures Claude Code

For individuals — memories stay on your machine, load automatically into every Claude Code session:

memo write decision   # interactive: name, description, content
memo recall "package manager"

For teams — commit .memobank/ like source code. Teammates get the same memories on clone:

git add .memobank/
git commit -m "init team memory"

Claude Code loads the first 200 lines of .memobank/MEMORY.md at every session start — no plugins, no configuration beyond memo onboarding.

How it works

memobank uses three memory tiers — like git config levels, each with a different scope:

| Tier | Location | Committed? | Scope | |------|----------|-----------|-------| | Personal | ~/.memobank/<project>/ | No | Your machine only | | Project | <repo>/<dir>/ (default: .memobank/) | Yes | Everyone who clones | | Workspace | ~/.memobank/_workspace/ | Separate remote | Across multiple repos |

Most teams only ever need Personal + Project. Workspace is opt-in. The project directory name (default .memobank) can be customized during memo onboarding.

When you run memo recall, memobank searches all active tiers and writes the top results to .memobank/MEMORY.md. Claude Code loads that file at the start of every session.

Memories are plain markdown with a small YAML header — readable, diffable, and reviewable in PRs:

---
name: prefer-pnpm
type: decision
status: active
tags: [tooling, packages]
---
We switched from npm to pnpm in March 2026. Faster installs, better monorepo support.

Why not just use CLAUDE.md?

CLAUDE.md is great for static rules you write once. memobank handles knowledge that accumulates over time — lessons learned, decisions made, patterns discovered. The two are complementary: CLAUDE.md for "always do X", memobank for "we learned Y".

Why not a cloud memory API?

Tools like mem0 or Zep store memories in external services. memobank stores them in your Git repo — no API keys, no vendor lock-in, no data leaving your machine. Memory health is visible in git diff. Reviews happen in PRs.

Why not Claude Code's built-in auto-memory?

Claude Code's auto-memory is personal and machine-local by default. memobank adds the team layer: .memobank/ is committed alongside your code, so every teammate and every CI run starts with the same shared knowledge. memobank also works with Cursor, Codex, Gemini CLI, and Qwen Code.

Features

Memory management

• Four types: lesson, decision, workflow, architecture
• Status lifecycle: experimental → active → needs-review → deprecated
• Automatic stale memory detection via memo review

Search

• Default: keyword + tag + recency scoring, zero external dependencies
• Optional: vector search via LanceDB (Ollama, OpenAI, Azure, Jina)

Safety

• Automatic secret redaction before every write (API keys, tokens, credentials)
• memo scan blocks workspace publish if secrets are detected

Integrations

• Claude Code — autoMemoryDirectory points to .memobank/, loads at session start
• Cursor, Codex, Gemini CLI, Qwen Code — hooks installed via memo onboarding
• Import from Claude Code, Gemini, and Qwen: memo import --claude

Team workflows

• Workspace tier: cross-repo knowledge synced via separate Git remote
• Epoch-aware scoring: team knowledge naturally fades during handoffs
• memo map for memory statistics, memo lifecycle for health scans

🗂️ Three-Tier Memory Model

Memobank organizes memory into three tiers, each with a distinct scope and use case. The tier determines where files are stored and who can access them — not how they are structured (all tiers share the same file format).

Tier 1 — Personal (Private)

| | | |---|---| | Location | ~/.memobank/<project-name>/ | | Committed to Git | Never | | Who sees it | Only you, on this machine | | Activate | memo init --global |

Use when: You want to keep private notes about a project — experiments that didn't pan out, personal shortcuts, machine-specific env quirks. This tier never touches the repo and is never shared.

~/.memobank/my-project/
├── lesson/
├── decision/
├── workflow/
└── architecture/

Tier 2 — Project (Team)

| | | |---|---| | Location | <repo-root>/.memobank/ | | Committed to Git | Yes — like any other source file | | Who sees it | Everyone who clones the repo | | Activate | memo init (default) |

Use when: You want the team to share knowledge about this repo. Adding a memory = opening a PR. Reviewing a memory = code review. History = git log. No extra commands needed — standard Git workflow handles everything.

your-project/
├── src/
├── .memobank/          ← committed alongside code
│   ├── lesson/
│   ├── decision/
│   ├── workflow/
│   └── architecture/
└── package.json

Differentiated use cases vs. personal:

• Bug post-mortems the whole team should know about → project
• "I personally keep forgetting to run npm run generate before building" → personal
• Architecture decision records (ADRs) → project
• Your local dev environment gotcha → personal

Tier 3 — Workspace (Organization, Optional)

| | | |---|---| | Location | ~/.memobank/_workspace/<workspace-name>/ (local clone) | | Committed to Git | To a designated remote repo (infra, platform-docs, etc.) | | Who sees it | Entire organization, across all repos | | Activate | memo workspace init <remote-url> |

Use when: You have knowledge that spans multiple repos or services — inter-service contracts, company-wide architecture patterns, platform team decisions. Any existing Git repo can serve as the workspace remote; updates flow through standard PRs.

Organization knowledge (cross-repo):
  [email protected]:mycompany/platform-docs.git
    └── .memobank/
        ├── lesson/       ← "all services must handle 429s with exponential backoff"
        ├── decision/     ← "we use gRPC for internal, REST for external"
        └── architecture/ ← "auth service owns all JWT validation"

Differentiated use cases vs. project:

• "Redis connection pooling pattern for this service" → project
• "Redis connection pooling pattern for all services" → workspace
• "We switched to Postgres in this repo" → project
• "Our data platform team maintains Postgres, contact @data-infra for schema changes" → workspace

Recall Priority

When memo recall runs, all configured tiers are searched and merged into a single ranked list:

Priority (highest → lowest):
1. Project   — most specific to current context
2. Personal  — your individual experience
3. Workspace — broad organizational knowledge

If the same filename exists in multiple tiers, the higher-priority tier's version wins. Each result shows its source tier so you always know where a memory came from.

📋 Commands

Setup & Configuration

| Command | Description | |---------|-------------| | memo onboarding | Interactive setup wizard (recommended) | | memo init | Alias for onboarding | | memo init --global | Set up personal (private) tier only | | memo install | Set up directory structure and platform hooks | | memo import | Import memories from other AI tools | | memo migrate | Migrate from old personal/+team/ layout to three-tier |

Memory Operations

| Command | Description | |---------|-------------| | memo recall <query> | Search all tiers and write results to MEMORY.md | | memo search <query> | Debug search without modifying MEMORY.md | | memo write <type> | Create a new memory (interactive or non-interactive) | | memo capture | Extract learnings from session text |

Workspace Commands

| Command | Description | |---------|-------------| | memo workspace init <url> | Configure workspace remote, clone to ~/.memobank/_workspace/ | | memo workspace sync | Pull latest workspace memories from remote | | memo workspace sync --push | Push local workspace changes to remote | | memo workspace publish <file> | Copy a project memory to workspace (+ secret scan) | | memo workspace status | Show git status of local workspace clone |

Management

| Command | Description | |---------|-------------| | memo index | Build/update search index | | memo review | List memories due for review | | memo map | Show memory statistics | | memo lifecycle | View memory lifecycle report | | memo lifecycle --scan | Run full status sweep (downgrades stale memories) | | memo lifecycle --reset-epoch | Reset epoch for team handoff (new team starts fresh decay) | | memo correct <path> | Record a memory correction | | memo scan | Scan for secrets before pushing |

🎯 Usage Examples

First Time Setup

# Interactive setup with menu navigation
memo onboarding        # or: memo init

# Project tier only (commits to repo)
memo init

# Personal tier only (private, never committed)
memo init --global

# Set up workspace for org-wide knowledge
memo workspace init [email protected]:mycompany/platform-docs.git

Create Memories

# Interactive (opens editor)
memo write lesson

# Non-interactive — project tier (default)
memo write lesson \
  --name="redis-pooling" \
  --description="Use connection pooling for Redis" \
  --tags="redis,database" \
  --content="## Problem\n\nHigh concurrency exhausts connections.\n\n## Solution\n\nUse connection pool with max=10."

# Write to personal tier explicitly
memo write lesson --scope personal \
  --name="local-dev-trick" \
  --description="Run port 3001 on this machine to avoid conflicts"

Search Memories

# Search all tiers (default)
memo recall "redis connection"

# Search specific tier
memo recall "redis connection" --scope project
memo recall "redis connection" --scope personal
memo recall "redis connection" --scope workspace

# Vector search (if configured)
memo recall "database pooling" --engine=lancedb

# Filter by tag or type
memo search "redis" --tag=database
memo search "pool" --type=lesson

# Show score breakdown
memo recall "redis" --explain

Share Memories with the Team

# Promote a personal note to project-level (committed with code)
# Just move the file and commit it — no special command needed
git add .memobank/lesson/redis-pooling.md
git commit -m "mem: add Redis pooling lesson"

# Promote a project memory to org-wide workspace
memo workspace publish .memobank/lesson/redis-pooling.md

# Pull latest org knowledge
memo workspace sync

Team Handoff

# New team takes over the project
git clone [email protected]:myorg/my-project.git   # project memories arrive automatically
memo workspace sync                               # pull latest org knowledge
memo lifecycle --reset-epoch                     # start fresh decay tracking

Import from Other Tools

memo import --claude    # Import from Claude Code
memo import --gemini    # Import from Gemini CLI
memo import --qwen      # Import from Qwen Code
memo import --all       # Import from all available tools

📁 Memory Types

| Type | Directory | Purpose | |------|-----------|---------| | Lesson | lesson/ | Post-mortems, bugs fixed, gotchas | | Decision | decision/ | ADRs: context, options, decision, consequences | | Workflow | workflow/ | Runbooks, deploy flows, onboarding | | Architecture | architecture/ | System diagrams, component descriptions |

Memory File Format

---
name: api-timeout-handling
type: lesson
description: "Use async job queue to prevent API timeout"
tags: [api, reliability, async]
created: 2026-03-17
status: active
confidence: medium
---

## Problem

[Describe the problem]

## Solution

[Describe the solution]

## Key Takeaways

- [Key insight 1]
- [Key insight 2]

📈 Status Lifecycle

Every memory has a status field that evolves based on how often it is recalled:

| Status | Meaning | Transition | |--------|---------|-----------| | experimental | Newly written, unverified | Default on creation | | active | Recalled at least once; trusted | Promoted on first recall | | needs-review | Not recalled in 90 days; may be stale | Downgraded by memo lifecycle --scan | | deprecated | Not recalled in 90 days after needs-review | Excluded from default recall |

Rules:

• experimental → active: recalled ≥ 1 time
• needs-review → active: recalled ≥ 3 times (deliberate re-validation required)
• deprecated memories remain searchable via memo search --include-deprecated but are excluded from memo recall
• The Git diff on .memobank/ shows which memories are gaining or losing relevance — your team's ambient health signal

# Manual lifecycle scan (or run in CI)
memo lifecycle --scan

# Configure thresholds in meta/config.yaml
lifecycle:
  experimental_ttl_days: 30
  active_to_review_days: 90
  review_to_deprecated_days: 90
  review_recall_threshold: 3

⚙️ Configuration

Configuration lives in meta/config.yaml (inside each tier's root):

project:
  name: "my-project"
  description: "Optional description"

memory:
  token_budget: 2000
  top_k: 5

embedding:
  engine: text        # or 'lancedb'
  provider: ollama    # or 'openai', 'azure'
  model: mxbai-embed-large
  dimensions: 1024

search:
  use_tags: true
  use_summary: true

lifecycle:
  experimental_ttl_days: 30
  active_to_review_days: 90
  review_to_deprecated_days: 90
  review_recall_threshold: 3
  decay_window_days: 180

workspace:
  enabled: true
  remote: [email protected]:mycompany/platform-docs.git
  path: .memobank      # subdirectory within remote repo (optional)
  branch: main
  auto_sync: false     # manual sync by default; no network on every recall

Embedding Providers

| Provider | Model | Dimensions | API Key | |----------|-------|------------|---------| | Ollama | mxbai-embed-large | 1024 | Not required | | OpenAI | text-embedding-3-small | 1536 | Required | | Azure | text-embedding-ada-002 | 1536 | Required |

🔌 Platform Integrations

After running memo install --all:

Claude Code

Sets autoMemoryDirectory in ~/.claude/settings.json

Codex

Appends memory protocol to AGENTS.md

Cursor

Creates .cursor/rules/memobank.mdc with alwaysApply: true

🛡️ Security

Memobank automatically sanitizes secrets before publishing to workspace:

• ✅ API keys and tokens
• ✅ Passwords and secrets
• ✅ IP addresses and hostnames
• ✅ Email addresses and phone numbers (PII)
• ✅ Database connection strings
• ✅ Private keys and certificates
• ✅ JWT tokens
• ✅ AWS credentials
• ✅ GitHub/GitLab tokens

memo workspace publish runs the same scanner and aborts if secrets are found — no automatic stripping, you must redact manually.

🔧 Development

# Clone and install
git clone https://github.com/clawde-agent/memobank-cli.git
cd memobank-cli
npm install

# Build
npm run build

# Run tests
npm test

# Development mode
npm run dev -- --help

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Areas for Contribution

• Unit and integration tests
• Additional embedding providers
• Platform integrations (VS Code, JetBrains)
• Performance optimizations
• Documentation improvements

📄 License

MIT © 2026 Memobank Project. See LICENSE for details.

🔗 Links

• npm package
• GitHub repository
• memobank-skill — AI Agent skill