changes

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

@@ -0,0 +1,48 @@
+---
+title: Memory System Main vs Per-Repo Project Split
+type: note
+permalink: opencode-config/decisions/memory-system-main-vs-per-repo-project-split
+tags:
+- 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]]