memobank-cli 0.2.0 → 0.6.0

package/CHANGELOG.md

@@ -14,6 +14,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Advanced search filters
 - Memory export formats (PDF, HTML)
 
+## [0.6.0] - 2026-03-20
+
+### Added
+
+- **Three-Tier Memory Model** — Personal (`~/.memobank/<project>/`), Project (`.memobank/`), Workspace (`~/.memobank/_workspace/`) tiers with distinct scopes and recall priority
+- **Custom project memory directory** — onboarding now prompts for the project tier directory name (default `.memobank`); any name is supported
+- **`findGitRoot` helper** — correctly resolves the git repo root independently of the memory directory name
+- **Auto-memory check step** — onboarding detects if Claude Code has `autoMemoryEnabled: false` and offers to re-enable it
+- **Workspace remote renamed from `team`** — `config.workspace` replaces `config.team`; backward-compatible alias in `loadConfig`
+
+### Changed
+
+- `MEMORY.md` now lives at `<repoRoot>/MEMORY.md` (flat, not `memory/MEMORY.md`)
+- `autoMemoryDirectory` in Claude Code settings points to the project tier root (not a subdirectory)
+- `findRepoRoot` scans all immediate subdirectories to support custom directory names
+- `memo onboarding` is the canonical setup command; `memo init` and `memo setup` remain as aliases
+- Deprecated `memo team` commands fully removed; use `memo workspace`
+- `--scope team` option removed; use `--scope project`
+
+### Fixed
+
+- Dead imports (`isNoise`, `hasHighValueIndicators`, `filterAndRank`) removed from `capture.ts`
+- Removed Stop hook install from Claude Code platform adapter (Claude Code native auto-memory handles writes)
+
 ## [0.1.0] - 2026-03-19
 
 ### Added

package/README.md

@@ -1,6 +1,4 @@
-# Memobank CLI
-
-> Persistent memory for AI coding sessions
+# memobank
 
 [![npm version](https://img.shields.io/npm/v/memobank-cli.svg)](https://www.npmjs.com/package/memobank-cli)
 [![npm downloads](https://img.shields.io/npm/dm/memobank-cli.svg)](https://www.npmjs.com/package/memobank-cli)
@@ -8,34 +6,215 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0-green.svg)](https://nodejs.org/)
 
-**Memobank CLI** is a personal AI memory system for coding agents. It provides persistent project memory (lessons, decisions, workflows, architecture) with automatic recall and capture.
+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.
 
-## 🚀 Quick Start
+---
+
+## Get started
 
 ```bash
-# Install globally
 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:
+
+```bash
+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:
+
+```bash
+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`.
 
-# Interactive setup (recommended)
-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 |
 
-# Or quick setup
-memo install --all
+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:
+
+```markdown
+---
+name: prefer-pnpm
+type: decision
+status: active
+tags: [tooling, packages]
+---
+We switched from npm to pnpm in March 2026. Faster installs, better monorepo support.
 ```
 
-## ✨ Features
+---
+
+## 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)
 
-- 🧠 **Automatic Recall** — Relevant memories injected at session start
-- 💾 **Structured Storage** — Markdown files with YAML frontmatter, Git-native
-- ⏳ **Decay Scoring** — Weibull-based relevance decay for recency prioritization
-- 🔍 **Hybrid Search** — Text engine (keyword + tag + decay) with optional LanceDB vector search
-- 🛡️ **Secret Sanitization** — Automatic redaction of API keys, tokens, PII, etc. (20+ patterns)
-- 🤖 **LLM Extraction** — Turn session summaries into structured memories
-- 🔌 **Multi-Platform** — Claude Code, Codex, Cursor, Gemini CLI, Qwen Code
-- 📦 **Zero-Dependency** — Text engine works out-of-the-box
-- 🌍 **Local Embeddings** — Ollama support (no API key needed)
-- 📥 **Memory Import** — Import from Claude Code, Gemini CLI, Qwen Code
-- 📊 **Lifecycle Management** — Track access patterns, archive inactive memories
+| | |
+|---|---|
+| **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):
+  git@github.com: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
 
@@ -45,18 +224,30 @@ memo install --all
 |---------|-------------|
 | `memo onboarding` | Interactive setup wizard (recommended) |
 | `memo init` | Alias for onboarding |
-| `memo install` | Set up directory structure |
+| `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 and display memories (writes to MEMORY.md) |
+| `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 |
@@ -65,7 +256,12 @@ memo install --all
 | `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
 
@@ -73,14 +269,16 @@ memo install --all
 
 ```bash
 # Interactive setup with menu navigation
-memo onboarding
+memo onboarding        # or: memo init
+
+# Project tier only (commits to repo)
+memo init
 
-# Quick automated setup
-memo install --all
+# Personal tier only (private, never committed)
+memo init --global
 
-# Configure specific platforms
-memo install --claude-code
-memo install --cursor
+# Set up workspace for org-wide knowledge
+memo workspace init git@github.com:mycompany/platform-docs.git
 ```
 
 ### Create Memories
@@ -89,70 +287,83 @@ memo install --cursor
 # Interactive (opens editor)
 memo write lesson
 
-# Non-interactive
+# 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
 
 ```bash
-# Text search
+# 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
+# Filter by tag or type
 memo search "redis" --tag=database
-
-# Filter by type
 memo search "pool" --type=lesson
+
+# Show score breakdown
+memo recall "redis" --explain
 ```
 
-### Lifecycle Management
+### Share Memories with the Team
 
 ```bash
-# View lifecycle report
-memo lifecycle report
+# 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"
 
-# View by tier
-memo lifecycle --tier core
-memo lifecycle --tier peripheral
+# Promote a project memory to org-wide workspace
+memo workspace publish .memobank/lesson/redis-pooling.md
 
-# View archival candidates
-memo lifecycle archive
-
-# View flagged memories (multiple corrections)
-memo lifecycle flagged
+# Pull latest org knowledge
+memo workspace sync
 ```
 
-### Import from Other Tools
+### Team Handoff
 
 ```bash
-# Import from Claude Code
-memo import --claude
-
-# Import from Gemini CLI
-memo import --gemini
+# New team takes over the project
+git clone git@github.com: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 Qwen Code
-memo import --qwen
+### Import from Other Tools
 
-# Import from all available tools
-memo import --all
+```bash
+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** | `lessons/` | Post-mortems, bugs fixed, gotchas |
-| **Decision** | `decisions/` | ADRs: context, options, decision, consequences |
-| **Workflow** | `workflows/` | Runbooks, deploy flows, onboarding |
+| **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
@@ -164,7 +375,7 @@ type: lesson
 description: "Use async job queue to prevent API timeout"
 tags: [api, reliability, async]
 created: 2026-03-17
-review_after: 90d
+status: active
 confidence: medium
 ---
 
@@ -182,31 +393,75 @@ confidence: medium
 - [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
+
+```bash
+# 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`:
+Configuration lives in `meta/config.yaml` (inside each tier's root):
 
 ```yaml
 project:
   name: "my-project"
   description: "Optional description"
+
 memory:
   token_budget: 2000
   top_k: 5
+
 embedding:
-  engine: text      # or 'lancedb'
-  provider: ollama  # or 'openai', 'azure'
+  engine: text        # or 'lancedb'
+  provider: ollama    # or 'openai', 'azure'
   model: mxbai-embed-large
   dimensions: 1024
+
 search:
   use_tags: true
   use_summary: true
-review:
-  enabled: true
+
 lifecycle:
-  coreThreshold: 10
-  peripheralThreshold: 90
-  archiveAfterDays: 180
+  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: git@github.com: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
@@ -217,6 +472,8 @@ lifecycle:
 | **OpenAI** | text-embedding-3-small | 1536 | Required |
 | **Azure** | text-embedding-ada-002 | 1536 | Required |
 
+---
+
 ## 🔌 Platform Integrations
 
 After running `memo install --all`:
@@ -230,9 +487,11 @@ Appends memory protocol to `AGENTS.md`
 ### Cursor
 Creates `.cursor/rules/memobank.mdc` with `alwaysApply: true`
 
+---
+
 ## 🛡️ Security
 
-Memobank automatically sanitizes:
+Memobank automatically sanitizes secrets before publishing to workspace:
 - ✅ API keys and tokens
 - ✅ Passwords and secrets
 - ✅ IP addresses and hostnames
@@ -243,21 +502,9 @@ Memobank automatically sanitizes:
 - ✅ AWS credentials
 - ✅ GitHub/GitLab tokens
 
-## 📊 Memory Lifecycle
-
-Memories are automatically categorized:
+`memo workspace publish` runs the same scanner and aborts if secrets are found — no automatic stripping, you must redact manually.
 
-| Tier | Condition | Behavior |
-|------|-----------|----------|
-| **Core** 🔴 | Access ≥10 times | Priority retrieval |
-| **Working** 🟡 | Normal access | Normal retrieval |
-| **Peripheral** ⚪ | 90 days no access | Lower priority, archive suggestion |
-
-## 📖 Documentation
-
-- [Onboarding Guide](docs/ONBOARDING-GUIDE.md) - Interactive setup walkthrough
-- [Memory Value Guide](docs/MEMORY-VALUE-GUIDE.md) - What to remember
-- [Lifecycle Management](docs/LIFECYCLE-MANAGEMENT.md) - Memory optimization
+---
 
 ## 🔧 Development