---
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]]