dotfiles/.config/opencode/decisions/Memory System Main vs Per-Repo Project Split.md

title, type, permalink, tags

title	type	permalink	tags
Memory System Main vs Per-Repo Project Split	note	opencode-config/decisions/memory-system-main-vs-per-repo-project-split	memory convention decision architecture

Memory System: Main vs Per-Repo Project Split

Decision

Adopted a strict two-project split for basic-memory:

• main is reserved exclusively for global/shared knowledge (reusable patterns, conventions, tech knowledge, user preferences, cross-project lessons)
• Each code repository gets its own dedicated basic-memory project for project-specific knowledge (plans, decisions, research, gates, sessions, architecture)

Observations

• [decision] main is global-only; never store project plans/decisions/research/gates/sessions in main #memory #convention
• [decision] Every repo must have a per-repo basic-memory project created via create_memory_project #memory #convention
• [decision] Session-start protocol requires identifying and selecting the per-repo project before any reads/writes #memory #convention
• [decision] All MCP calls must pass the project parameter explicitly — project="main" for global, project="<repo-project-name>" for project-specific #memory #convention
• [decision] Repo-local .memory/ directories are legacy artifacts, renamed to .memory.legacy/ #memory

Affected Files (opencode-config repo)

• AGENTS.md — core memory system section rewritten with main/per-repo split, session-start protocol, project setup instructions
• commands/init.md — Step 5 creates per-repo basic-memory project
• commands/bootstrap-memory.md — Step 0 ensures per-repo project, all steps pass project parameter
• commands/save-memory.md — distinguishes main vs per-repo targets
• commands/status.md — requires per-repo project identification
• commands/plan.md — per-repo project targeting for plans/decisions/research
• commands/sme.md — split guidance caching between main and per-repo
• commands/research.md — split project targeting
• commands/review.md — per-repo project targeting
• commands/test.md — per-repo project targeting
• commands/docs.md — per-repo project targeting
• agents/lead.md — session-start project identification, all note sections updated
• agents/sme.md — explicit main vs per-repo caching workflow
• agents/librarian.md — updated to enforce main/per-repo split in docs
• agents/reviewer.md — per-repo project recording
• agents/tester.md — per-repo project recording
• agents/critic.md — per-repo project recording
• agents/designer.md — per-repo project recording
• skills/git-workflow/SKILL.md — clarified per-repo/main in legacy note

Relations

• related_to opencode-config Knowledge Overview