Proposal: ADR-001 hybrid memory architecture (8 gaps for AI-agent use cases)

[mdcruz88]

Context

Filed alongside #668 (forward-reference bootstrap fix). I've been running gbrain as an AI agent's persistent memory layer (Claude Code + Codex CLI sharing the same brain), and over time identified eight gaps that would make gbrain materially more useful in that role. I've prototyped all eight in a fork — happy to PR as separate units once we agree on direction.

The eight gaps

Gap #1 — Privacy enforcement

• --respect-sensitivity flag on gbrain import honors a sensitivity: public | project | private frontmatter field
• memory/private/ skip-directory rule
• Purge-on-tightening behavior — when sensitivity changes from public to private, prior public-side embeddings are deleted

Gap #1.5 — Source-aware CRUD

• getPage / putPage / deletePage accept an optional sourceId parameter (currently route through default)
• gbrain import --source <id> auto-registers the source if it doesn't exist (today the --source flag is silently dropped — see import.ts)

Gap #3 — Source-path tracking on pages

• New pages.source_path TEXT column captures the on-disk origin file
• Threaded through schema, both engines, types, rowToPage, importFromFile
• Foundation for Gaps docs: expand brain schema with database architecture and OSS smoothing #4 and feat: GBrain v0.3.0 — contract-first architecture + ClawHub plugin #7

Gap #4 — Audit-aware delete reconciliation

• gbrain import --purge-deleted flag finds pages whose source_path falls under the import dir but whose underlying file no longer exists, and cascade-deletes them
• Solves the "agent renamed/deleted a memory file, brain still has the orphan" class of issue

Gap #5 — Single-file gbrain import

• gbrain import path/to/single-file.md works (currently requires a directory)
• Plus a CLAUDE.md / AGENTS.md hook pattern for SessionEnd flush — the agent writes a memory file mid-session, single-file import lands it without rescanning

Gap #6 — SessionStart brief MCP operation

• New MCP op returning a ≤800-token "session card" with source refs + relevance scores + graceful fallback
• Backed by JSONL observability log so an agent can see what got loaded and why
• Different from query — this is "what's important in my brain right now" not "answer this question"

Gap #7 — gbrain audit command

• gbrain audit [--fix] detects four classes of brain pathology:
  • Ghosts: pages whose source_path points at a file that no longer exists
  • Drift: pages whose source_path exists but content_hash no longer matches the file (someone edited the file but didn't re-import)
  • Stale_fs: files in source_path territory that aren't represented as pages (someone added a file but didn't import)
  • Decay: pages that haven't been accessed in N days

Gap #8 — Backfill gate (docs)

• CLAUDE.md / agent-config sequencing constraint: privacy enforcement (feat: GBrain v0.1.0 — Postgres-native personal knowledge brain #1) ships first, source-aware CRUD (feat: GBrain v0.1.0 — Postgres-native personal knowledge brain #1.5) follows, agent-side wiring last
• No code, just operator discipline documented

Reference implementation

All eight gaps prototyped on a fork branch: https://github.com/mdcruz88/gbrain/tree/michael/adr-001-hybrid-memory

That branch is currently 12 commits behind master (predates v0.26 OAuth + admin dashboard), so a clean rebase is real work. Filing this Issue now to get architectural feedback BEFORE I spend the time porting forward. If the proposal lands, I'll follow up with PRs in this order:

1. Source-tracking foundation (Gaps docs: fix first-time experience — remove fictional kindling, add recommended schema #3 + feat: GBrain v0.1.0 — Postgres-native personal knowledge brain #1.5 + docs: expand brain schema with database architecture and OSS smoothing #4 + feat: GBrain v0.3.0 — contract-first architecture + ClawHub plugin #7 — they coevolve naturally)
2. Privacy enforcement (Gap feat: GBrain v0.1.0 — Postgres-native personal knowledge brain #1)
3. brief MCP op (Gap SQLite integration #6)
4. Single-file import (Gap feat: OpenClaw plugin — Phase 1 core search #5)

Why this matters for gbrain's broader user base

The shape of "AI agent's memory" is converging across Claude Code, Codex CLI, Cursor, and the rest. Today every agent is wiring up its own ad-hoc solution (~/.claude/projects/.../memory/*.md, Codex's transcript tail, etc.). gbrain is uniquely positioned to be the shared substrate — agent-agnostic, locally-private-by-default, queryable. The eight gaps are the seams I hit when wiring Claude Code memory through gbrain. Other agent users will hit the same seams.

Happy to discuss scope, reorder, or split. Looking for a thumbs up before I invest in the rebase + PR series.

🤖 Generated with Claude Code

[mdcruz88]

Not pursuing locally — closing. The local prototype branch is being deleted; the design lives in this issue's body for archaeology only. Re-open if/when there's appetite from maintainers.