# PRD: Super Memory — Persistent Knowledge Infrastructure for Agentic Development

**Version:** 0.1.0
**Author:** Mitch Carter
**Date:** 2026-02-06
**Status:** Draft

---

## 1. Problem Statement

AI coding agents (Claude Code, Cursor, Aider, Open Code) suffer from **session amnesia**. Every new session starts cold — rediscovering architecture, re-exploring codebases, repeating mistakes that were fixed days ago. On teams, this compounds: 4 developers running agent sessions means 4x the redundant exploration, with no shared knowledge accumulation.

Existing tools solve adjacent problems but not this one:

| Tool | What It Tracks | Gap |
|------|---------------|-----|
| Git | Code changes | No conceptual knowledge |
| Beads / Linear / Jira | Tasks (what to do / was done) | Not queryable by concept |
| CLAUDE.md / .cursorrules | Static project rules | Not updated by agents, no team state |
| Claude Code MEMORY.md | Per-user notes | Not shared, not structured, 200-line limit |

**Super Memory** fills the gap: a shared, structured, agent-readable knowledge layer that accumulates intelligence across sessions and team members.

---

## 2. Vision

A `.memory/` directory in any repo that:

1. **Any AI agent can read** (it's markdown files with frontmatter)
2. **Any AI agent can write** (standard file operations, no special API)
3. **Teams share via git** (committed knowledge) while keeping local scratch (gitignored)
4. **Obsidian provides the UI** (graph view, tag queries, backlinks — for free)
5. **Installs in 30 seconds** via `curl` or package manager

---

## 3. Target Users

- **Primary:** Developers using AI coding agents (Claude Code, Cursor, Aider, Open Code) on team projects
- **Secondary:** Solo developers wanting persistent agent memory across sessions
- **Tertiary:** Teams wanting lightweight knowledge management without a wiki

---

## 4. Core Concepts

### 4.1 Knowledge Types

| Type | Directory | Purpose | Git Status |
|------|-----------|---------|------------|
| **System Docs** | `systems/` | Architecture of each subsystem — files, patterns, integration points | Committed |
| **Decisions** | `decisions/` | Architectural Decision Records — why things are the way they are | Committed |
| **Gotchas** | `gotchas/` | Known pitfalls, bugs that were fixed, anti-patterns discovered | Committed |
| **Research** | `research/` | Investigation findings, API behavior, external constraints | Committed |
| **People** | `people/` | Per-person context — current focus, ownership, preferences | Committed |
| **Sessions** | `sessions/` | Per-session summaries — what was done, what was left off | Gitignored |
| **Scratch** | `scratch/` | Working memory during a session — promoted to permanent after | Gitignored |

### 4.2 Session Lifecycle

Every agent session follows three phases:

```
WARMUP (read) ──▶ WORK (write-through) ──▶ COOLDOWN (commit knowledge)
```

- **Warmup:** Agent reads relevant system docs, recent sessions, person file, gotchas
- **Work:** Agent appends discoveries to scratch/ as it works
- **Cooldown:** Agent promotes scratch to permanent memory, updates person file, writes session summary

### 4.3 Tagging (Thin, Two-Dimensional)

Memory files use frontmatter tags for agent retrieval. Two dimensions only:

- **System tags:** Which subsystem (derived from `systems/` directory names)
- **Concern tags:** What kind of knowledge (defined in config, max ~10)

```yaml
# Concern tags (examples — configured per-project)
concerns:
  - race-condition
  - api-quirk
  - performance
  - security
  - data-integrity
  - cost
  - breaking-change
```

Tags exist for **agent retrieval**, not human organization. The agent thinks: *"I'm about to modify the trigger system"* → queries all files tagged `trigger-system` → reads 3 files instead of exploring 50 source files.

### 4.4 Beads Integration

Super Memory does NOT replace issue trackers. It complements them.

| Beads (Task Tracker) | Super Memory (Knowledge Layer) |
|----------------------|-------------------------------|
| "What needs doing?" | "What do I need to know?" |
| Status, priority, assignment | Architecture, gotchas, decisions |
| Temporal (when created/closed) | Conceptual (by system/concern) |
| Every task tracked | Only lasting knowledge preserved |

**Sync point:** When closing a bead that produced lasting knowledge, the agent creates/updates a memory file with a `beads: [id]` backlink in frontmatter. This is a manual promotion, not auto-sync. Most tasks don't produce knowledge worth preserving.

### 4.5 Obsidian as UI

Obsidian reads a directory of markdown files as a "vault." `.memory/` IS that vault.

**Zero-config integration:** Point Obsidian at `.memory/` and you immediately get:

- **Graph View:** Visualize connections between systems, gotchas, decisions, people
- **Tag Pane:** Filter by system or concern tags
- **Backlinks:** Click a system doc → see all gotchas, decisions, sessions that reference it
- **Dataview Plugin:** Query frontmatter programmatically (e.g., "all gotchas with severity: high")
- **Search:** Full-text search across all knowledge

**What Obsidian adds that raw files don't:**

| Feature | How It Maps to .memory/ |
|---------|------------------------|
| Graph view | Systems → gotchas → decisions connections visible |
| Backlinks | `[[trigger-system]]` links in gotchas auto-resolve |
| Tag filtering | `#race-condition` across all files |
| Dataview tables | "Show all stale system docs (last_verified > 7 days ago)" |
| Daily notes | Maps to `sessions/` — one note per session |
| Templates | Maps to `_template.md` files in each directory |
| Kanban (plugin) | Visualize people's current focus areas |

**Obsidian-specific configuration:**

```
.memory/
├── .obsidian/                    # Obsidian workspace config (gitignored)
│   ├── workspace.json
│   ├── app.json
│   └── plugins/
│       ├── dataview/             # Frontmatter queries
│       └── templater/            # Use _template.md files
```

**Recommended Obsidian setup (generated by install):**

```json
// .memory/.obsidian/app.json
{
  "defaultViewMode": "preview",
  "showFrontmatter": false,
  "useMarkdownLinks": false,
  "newLinkFormat": "shortest",
  "attachmentFolderPath": ".memory/attachments"
}
```

**Wikilink conventions for Obsidian graph:**

Memory files should use `[[wikilinks]]` to reference other memory files. This enables Obsidian's graph view and backlink panel.

```markdown
# .memory/gotchas/dual-evaluation-race.md

## Related
- System: [[trigger-system]]
- Also affects: [[conditional-monitor]]
- Decision: [[emulated-triggers-for-options]]
```

In the graph, this creates visible edges between the gotcha and the systems it affects.

---

## 5. Directory Structure

```
.memory/
├── config.yaml                   # Project + team config (committed)
├── .me                           # Local identity file (gitignored)
├── AGENT_PROTOCOL.md             # Instructions any AI agent reads (committed)
├── SUMMARY.md                    # Auto-generated index (committed)
│
├── systems/                      # Subsystem architecture docs (committed)
│   ├── _template.md
│   └── {system-name}.md
│
├── decisions/                    # Architectural Decision Records (committed)
│   ├── _template.md
│   └── {NNN}-{slug}.md          # Numbered for ordering
│
├── gotchas/                      # Known pitfalls (committed)
│   ├── _template.md
│   └── {slug}.md
│
├── research/                     # Investigation findings (committed)
│   ├── _template.md
│   └── {slug}.md
│
├── people/                       # Per-person context (committed)
│   ├── _template.md
│   └── {name}.md
│
├── sessions/                     # Session logs (gitignored)
│   └── {date}-{person}-{topic}.md
│
├── scratch/                      # Working memory (gitignored)
│   └── {anything}.md
│
└── .obsidian/                    # Obsidian workspace (gitignored)
    └── ...
```

---

## 6. Configuration

### 6.1 config.yaml

```yaml
# .memory/config.yaml — Super Memory Configuration

# ──────────────────────────────────────────────
# Project
# ──────────────────────────────────────────────
project:
  name: ""                         # Auto-detected from git remote or directory
  description: ""                  # One-liner

# ──────────────────────────────────────────────
# Team
# ──────────────────────────────────────────────
team:
  members:
    - id: ""                       # Short name (used in .me, filenames)
      role: ""                     # architect | engineer | lead | etc
      areas: []                    # Systems they own/work on

# Local identity — NOT in config.yaml (gitignored)
# Set via: echo "mitch" > .memory/.me
# Or: export MEMORY_USER=mitch

# ──────────────────────────────────────────────
# Systems (subsystem discovery)
# ──────────────────────────────────────────────
systems:
  auto_discover: true              # Scan codebase for module boundaries
  discover_paths:                  # Where to look for modules
    - "src/"
  discover_depth: 3                # How deep to scan for __init__.py / index.ts
  ignore:                          # Skip these directories
    - "node_modules"
    - "__pycache__"
    - ".venv"

# ──────────────────────────────────────────────
# Tags
# ──────────────────────────────────────────────
tags:
  # System tags are auto-derived from systems/ directory
  # Concern tags are defined here (max ~10)
  concerns:
    - race-condition
    - api-quirk
    - performance
    - security
    - data-integrity
    - cost
    - breaking-change

# ──────────────────────────────────────────────
# Memory behavior
# ──────────────────────────────────────────────
memory:
  stale_after_days: 7              # Flag system docs older than this
  verify_on_code_change: true      # Flag docs when their source paths change
  max_session_history: 20          # Keep last N session summaries
  auto_summary: true               # Regenerate SUMMARY.md after memory writes

# ──────────────────────────────────────────────
# Integrations
# ──────────────────────────────────────────────
integrations:
  # Issue tracker backlinks
  beads: false                     # Enable beads: [] frontmatter field
  linear: false                    # Enable linear: [] frontmatter field
  github_issues: false             # Enable github: [] frontmatter field
  jira: false                      # Enable jira: [] frontmatter field

  # Agent platform hooks
  claude_code: false               # Append protocol to CLAUDE.md, install hooks
  cursor: false                    # Append protocol to .cursorrules
  aider: false                     # Generate .aider.conf.yml reference

  # UI
  obsidian: false                  # Generate .obsidian/ config, enable wikilinks

# ──────────────────────────────────────────────
# Git
# ──────────────────────────────────────────────
git:
  # What gets committed
  shared:
    - "systems/"
    - "decisions/"
    - "gotchas/"
    - "research/"
    - "people/"
    - "config.yaml"
    - "AGENT_PROTOCOL.md"
    - "SUMMARY.md"
  # What stays local (added to .gitignore)
  local:
    - "sessions/"
    - "scratch/"
    - ".me"
    - ".obsidian/"
```

### 6.2 .me (Local Identity)

```
mitch
```

Single line. The person name that matches a `team.members[].id` in config.yaml. Set per-machine, never committed. Can also be set via `MEMORY_USER` env var.

---

## 7. File Templates

### 7.1 System Doc

```markdown
<!-- .memory/systems/_template.md -->
---
owner:
last_verified:
paths: []
tags: []
---

# {System Name}

## Purpose

What this system does in one paragraph.

## Architecture

Key patterns, data flow, abstractions. Include a brief diagram if helpful.

## Key Files

- `path/to/main.py` — entry point
- `path/to/models.py` — data models

## Integration Points

How this system connects to other systems. Use [[wikilinks]] to reference
other system docs.

## Configuration

Environment variables, config files, feature flags that affect this system.

## Known Gotchas

Link to relevant gotcha docs:
- [[gotcha-name]]
```

### 7.2 Decision Record

```markdown
<!-- .memory/decisions/_template.md -->
---
number:
date:
author:
status: active          # active | superseded | revisit
superseded_by:          # decision number, if superseded
tags: []
beads: []               # issue tracker backlinks
---

# {NNN}: {Decision Title}

## Context

What situation prompted this decision? What constraints exist?

## Decision

What we decided to do.

## Alternatives Considered

What else was on the table and why we rejected it.

## Consequences

What this decision enables, prevents, or requires going forward.
```

### 7.3 Gotcha

```markdown
<!-- .memory/gotchas/_template.md -->
---
severity: medium        # high | medium | low
systems: []             # [[system-name]] references
tags: []
discovered:
beads: []               # issue tracker backlinks
---

# {Gotcha Title}

## The Problem

What goes wrong and when. Be specific about conditions.

## The Fix

What was done to address it. Include file paths and key code references.

## How to Avoid

What a developer (or agent) should do to not repeat this.
```

### 7.4 Research

```markdown
<!-- .memory/research/_template.md -->
---
date:
author:
status: current         # current | outdated | needs-update
systems: []
tags: []
beads: []
expires:                # optional — date when findings should be re-verified
---

# {Research Topic}

## Question

What we needed to find out.

## Findings

What we learned. Be specific — include URLs, API responses, version numbers.

## Implications

What this means for the project. Link to systems/decisions affected.

## Sources

Where the information came from. URLs, docs, experiments.
```

### 7.5 Person

```markdown
<!-- .memory/people/_template.md -->
---
id:
role:
areas: []
---

# {Person Name}

## Current Focus

What they're actively working on right now.

## Last Session

**Date:**
**Topic:**
**Summary:**
**Left off at:**

## Owns

Systems and areas this person is primary owner of.

## Working On (DO NOT TOUCH)

Files/systems currently being modified. Other agents should avoid these
to prevent merge conflicts.

- `path/to/file.py` — reason

## Preferences

Coding style preferences, tool preferences, anything that helps an agent
work the way this person expects.
```

### 7.6 Session

```markdown
<!-- .memory/sessions/_template.md -->
---
date:
person:
topic:
duration:               # approximate
systems_touched: []
---

# Session: {topic}

## What Was Done

Bullet list of accomplishments.

## What Was Learned

Discoveries that might be worth promoting to permanent memory.

## What's Left

Unfinished work, next steps.

## Files Modified

- `path/to/file.py` — what changed
```

---

## 8. Agent Protocol

The following is written to `.memory/AGENT_PROTOCOL.md` and referenced from CLAUDE.md / .cursorrules / equivalent. It is the **single source of truth** for how agents interact with memory.

```markdown
# Super Memory — Agent Protocol

This project uses `.memory/` for persistent shared knowledge.
Follow this protocol every session.

## Identity

Read `.memory/.me` (or $MEMORY_USER) to identify your human operator.
Read `.memory/people/{me}.md` for their context.

## Session Start (Warmup)

Before starting work:

1. Read `.memory/people/{me}.md`:
   - What were they last working on?
   - What did they leave unfinished?
   - What files are marked DO NOT TOUCH?

2. Identify which systems your task touches:
   - Check `.memory/config.yaml` → systems paths
   - Or infer from the files you'll modify

3. Read relevant `.memory/systems/{system}.md` docs:
   - Architecture, integration points, known gotchas

4. Read `.memory/gotchas/*` tagged with those systems

5. Read `.memory/decisions/*` tagged with those systems

6. Scan last 3 entries in `.memory/sessions/` for recent team activity

You now have full context. Begin work.

## During Work

When you discover something non-obvious, append to `.memory/scratch/`:

- API quirks: "Alpaca returns 'BuyToClose' not 'buy_to_close'"
- Architecture insights: "X and Y share no coordination lock"
- Performance findings: "Batch size > 10 causes timeouts"
- Failed approaches: "Tried X, didn't work because Y"

Use any filename in scratch/. These are temporary.

## Session End (Cooldown)

Before ending the session:

1. **Update person file** `.memory/people/{me}.md`:
   - Current focus → what's in progress now
   - Last session → date, topic, summary, left off at
   - Working on → files being actively modified (or clear if done)

2. **Update system docs** if you changed how a system works:
   - `.memory/systems/{system}.md` — update architecture, files, integration points
   - Set `last_verified` to today's date

3. **Create gotcha docs** if you found a bug pattern or pitfall:
   - `.memory/gotchas/{slug}.md` using the template
   - Tag with relevant systems and concerns

4. **Create decision docs** if you made an architectural choice:
   - `.memory/decisions/{NNN}-{slug}.md` using the template
   - Number sequentially from last decision

5. **Promote scratch** — move lasting knowledge from `scratch/` to the
   appropriate permanent directory. Delete scratch files that are no longer needed.

6. **Write session summary** `.memory/sessions/{date}-{person}-{topic}.md`

## Conventions

### Wikilinks
Use `[[filename]]` (without directory prefix) to link between memory files.
This enables Obsidian graph view and backlinks.

Example in a gotcha: `Systems: [[trigger-system]], [[conditional-monitor]]`

### Frontmatter
All memory files use YAML frontmatter. Required fields vary by type —
see templates in each directory (`_template.md`).

### Tags
- System tags: match names in `.memory/systems/` directory
- Concern tags: defined in `.memory/config.yaml` → tags.concerns
- Apply both dimensions when relevant

### Staleness
If a system doc's `last_verified` date is older than `memory.stale_after_days`
from config, flag it in your session summary and update it if you have context.

### Conflict Avoidance
- Check `.memory/people/*.md` → "Working On (DO NOT TOUCH)" before modifying shared files
- If someone else is working on the same system, note the conflict and coordinate
```

---

## 9. Installation

### 9.1 CLI Interface

```bash
# Install the CLI
pip install supermemory    # or: npm install -g supermemory
                           # or: cargo install supermemory
                           # or: curl -sSL .../install.sh | bash

# Initialize in a project
supermemory init

# Interactive prompts:
#   Project name: (auto-detected)
#   Your name: mitch
#   Team members: (comma-separated or skip)
#   Agent platform: claude-code / cursor / aider / none
#   Issue tracker: beads / linear / github / jira / none
#   Enable Obsidian: y/n
#   Auto-discover systems: y/n

# Non-interactive (CI/scripts)
supermemory init \
  --project "my-project" \
  --me mitch \
  --platform claude-code \
  --tracker beads \
  --obsidian \
  --auto-discover
```

### 9.2 What `init` Does

```
1. mkdir -p .memory/{systems,decisions,gotchas,research,people,sessions,scratch}
2. Write .memory/config.yaml (from answers or defaults)
3. Write .memory/AGENT_PROTOCOL.md
4. Write _template.md into each subdirectory
5. Write .memory/.me with user identity
6. Create .memory/people/{me}.md from template
7. Add gitignore entries (sessions/, scratch/, .me, .obsidian/)

If --platform claude-code:
  8. Append memory protocol reference to CLAUDE.md
  9. Optionally install session hooks in .claude/settings.json

If --platform cursor:
  8. Append memory protocol to .cursorrules

If --obsidian:
  8. Create .memory/.obsidian/ with app.json, workspace defaults
  9. Install recommended plugin configs (dataview, templater)

If --auto-discover:
  8. Scan codebase for modules
  9. Create skeleton .memory/systems/{module}.md for each
  10. Print discovered systems for review

If --tracker beads:
  8. Set integrations.beads: true in config
  9. Add beads: [] to all templates
```

### 9.3 Other CLI Commands

```bash
# Identity
supermemory whoami                     # Print current .me identity
supermemory whoami mitch               # Set .me identity

# Systems
supermemory systems                    # List all system docs
supermemory systems discover           # Re-scan and create new system docs
supermemory systems stale              # Show system docs past staleness threshold

# Query (agent-oriented, outputs markdown)
supermemory query --system trigger-system
# Returns: all memory files tagged with trigger-system

supermemory query --concern race-condition
# Returns: all memory files tagged with race-condition

supermemory query --system trigger-system --concern api-quirk
# Returns: intersection

# Summary
supermemory summary                    # Regenerate SUMMARY.md (index of all memory)

# Health
supermemory health                     # Check for:
                                       #   - Stale system docs
                                       #   - People with no recent sessions
                                       #   - Orphaned scratch files
                                       #   - Systems with no docs
                                       #   - Templates missing
```

---

## 10. Obsidian Integration (Detail)

### 10.1 Setup

When `--obsidian` is passed to `supermemory init`:

1. Create `.memory/.obsidian/` directory
2. Generate `app.json` with markdown-optimized settings
3. Generate `community-plugins.json` referencing recommended plugins
4. Generate starter `workspace.json` with graph view open

The user then:
1. Opens Obsidian
2. "Open folder as vault" → selects `.memory/`
3. Installs recommended community plugins when prompted

### 10.2 Recommended Plugins

| Plugin | Purpose |
|--------|---------|
| **Dataview** | Query frontmatter across all files. "Show all high-severity gotchas." |
| **Templater** | Use `_template.md` files when creating new notes via Obsidian |
| **Calendar** | Navigate sessions by date |
| **Graph Analysis** | Enhanced graph view with clustering by tags |
| **Kanban** (optional) | Visualize team member focus areas as columns |

### 10.3 Dataview Queries (Pre-Built)

The SUMMARY.md file includes Dataview queries that render in Obsidian:

```markdown
## Stale System Docs

```dataview
TABLE owner, last_verified, paths
FROM "systems"
WHERE date(now) - date(last_verified) > dur(7 days)
SORT last_verified ASC
`` `

## High Severity Gotchas

```dataview
TABLE severity, systems, discovered
FROM "gotchas"
WHERE severity = "high"
SORT discovered DESC
`` `

## Active Decisions

```dataview
TABLE date, author, status
FROM "decisions"
WHERE status = "active"
SORT number DESC
`` `

## Team Activity (Last 7 Days)

```dataview
TABLE person, topic, systems_touched
FROM "sessions"
WHERE date(date) > date(now) - dur(7 days)
SORT date DESC
`` `
```

### 10.4 Wikilink Graph

With `[[wikilinks]]` in memory files, Obsidian's graph view shows:

```
                    ┌──────────────┐
               ┌───▶│ trigger-system│◀──── gotcha: dual-eval-race
               │    └──────────────┘
               │           ▲
  decision: ───┤           │
  emulated-    │    ┌──────┴───────┐
  triggers ────┼───▶│ cond-monitor │◀──── gotcha: trailing-stop
               │    └──────────────┘
               │           ▲
               │    ┌──────┴───────┐
               └───▶│ price-stream │◀──── gotcha: ws-conn-limits
                    └──────────────┘
                           ▲
                    ┌──────┴───────┐
                    │   brandon    │ (owner of all three)
                    └──────────────┘
```

This gives the team a **visual map of knowledge** — not code, but understanding.

---

## 11. Platform Hook Specifications

### 11.1 Claude Code

**CLAUDE.md append:**

```markdown
## Project Memory

This project uses Super Memory (`.memory/`) for persistent shared knowledge.
Read `.memory/AGENT_PROTOCOL.md` for the full protocol.

On session start: read your person file and relevant system docs.
On session end: update person file, write session summary, promote scratch.
```

**Optional hooks (.claude/settings.json):**

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "supermemory check-conflict \"$FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}
```

The `check-conflict` hook reads people/*.md "DO NOT TOUCH" sections and warns if the agent is modifying a file another team member has claimed.

### 11.2 Cursor

**Append to .cursorrules:**

The full contents of AGENT_PROTOCOL.md get appended, since Cursor reads .cursorrules on every prompt.

### 11.3 Aider

**Generate .aider.conf.yml:**

```yaml
read:
  - .memory/AGENT_PROTOCOL.md
  - .memory/people/.me
```

---

## 12. Package Structure

```
supermemory/
├── pyproject.toml              # Package metadata (or package.json / Cargo.toml)
├── README.md
├── LICENSE
│
├── src/
│   └── supermemory/
│       ├── __init__.py
│       ├── cli.py              # CLI entry point (typer or click)
│       ├── init.py             # Project initialization logic
│       ├── discover.py         # System auto-discovery
│       ├── query.py            # Tag-based memory query
│       ├── health.py           # Staleness/health checks
│       ├── summary.py          # SUMMARY.md generation
│       ├── hooks.py            # Platform hook generation
│       ├── obsidian.py         # Obsidian config generation
│       └── config.py           # Config parsing/validation
│
├── templates/                  # Installed into .memory/
│   ├── AGENT_PROTOCOL.md
│   ├── config.yaml
│   ├── SUMMARY.md
│   ├── system.md
│   ├── decision.md
│   ├── gotcha.md
│   ├── research.md
│   ├── person.md
│   └── session.md
│
├── obsidian/                   # Obsidian config templates
│   ├── app.json
│   ├── workspace.json
│   └── community-plugins.json
│
├── install.sh                  # curl-installable script
│
└── tests/
    ├── test_init.py
    ├── test_discover.py
    ├── test_query.py
    ├── test_health.py
    └── test_hooks.py
```

---

## 13. Technical Decisions

### 13.1 Why Markdown, Not a Database

- Every AI agent can read/write files. Not every agent has SQLite access.
- Git diff shows exactly what knowledge changed and when.
- Obsidian requires a file-per-note model.
- No daemon, no server, no process to manage.
- Markdown with YAML frontmatter is the universal interchange format for AI tools.

### 13.2 Why Frontmatter Tags, Not a Separate Index

- Tags live with the content. No sync drift between index and files.
- Obsidian Dataview queries frontmatter natively.
- `supermemory query` can grep frontmatter with zero dependencies.
- Agent can read tags inline while reading the file.

### 13.3 Why Not Auto-Sync from Issue Tracker

- Most tasks don't produce lasting knowledge. Auto-sync creates noise.
- The value is in the **curation** — an agent deciding "this is worth remembering."
- Backlinks (`beads: [id]`) provide traceability without duplication.
- Different projects use different trackers. The backlink field is configurable.

### 13.4 Why Session Logs Are Gitignored

- They're high-volume, low-signal for other team members.
- They contain working-memory-level detail that becomes noise after 48 hours.
- The lasting knowledge from sessions gets promoted to permanent memory.
- Prevents .memory/ from bloating the repo over time.

### 13.5 Language Choice for CLI

**Recommended: Python** (with `uv` for fast install)

- Largest AI-developer user base
- `typer` for CLI, `pyyaml` for config, `pathlib` for file ops
- No heavy dependencies. Entire package should be < 500 lines.
- Install via `uvx supermemory init` (no persistent install needed)

**Alternative: Shell-only (zero dependencies)**

- install.sh + a few bash scripts
- More universal but harder to maintain
- Good for v0, graduate to Python for query/health features

---

## 14. Success Criteria

### For a Solo Developer

- [ ] `supermemory init` creates working .memory/ in < 30 seconds
- [ ] Agent reads system docs and avoids known gotchas without being told
- [ ] Session warmup replaces 5+ minutes of codebase exploration
- [ ] Knowledge persists across context window resets

### For a 4-Person Team

- [ ] All team members' agents can read shared memory from git
- [ ] "DO NOT TOUCH" in person files prevents agent merge conflicts
- [ ] New team member's agent is productive in first session (reads systems/ + people/)
- [ ] Gotchas are never re-discovered — agent reads the fix before repeating the mistake
- [ ] Obsidian graph shows team knowledge topology

### For Universal Adoption

- [ ] Works on any project (Python, TypeScript, Rust, Go, polyglot)
- [ ] Works with any AI agent (Claude Code, Cursor, Aider, generic)
- [ ] Works with any issue tracker (beads, Linear, GitHub, Jira) or none
- [ ] Install is a single command
- [ ] Zero runtime dependencies for basic usage (file reads/writes only)
- [ ] Under 500 lines of implementation code

---

## 15. Out of Scope (v1)

- Real-time sync between team members (git push/pull is sufficient)
- Memory conflict resolution UI (git merge is sufficient)
- Automated knowledge extraction from code changes
- MCP server (future: expose memory as tools for agents)
- Embedding-based semantic search (future: for large memory vaults)
- Memory analytics dashboard (Obsidian Dataview covers this)
- Mobile/web UI (Obsidian handles cross-platform)

---

## 16. Open Questions

1. **Should sessions/ be gitignored or committed?** Current decision: gitignored (high volume, becomes noise). But some teams might want session history shared. Make it configurable.

2. **How to handle memory file conflicts in git?** Two agents updating the same system doc simultaneously. Options: last-write-wins (current), merge via append-only sections, or ownership-based locking.

3. **Should `supermemory query` be an MCP tool?** Would allow agents to query memory without file reads. Adds complexity but enables richer retrieval. Defer to v2.

4. **How much should auto-discover infer?** Currently: find modules, create skeleton docs. Could also: parse imports for integration points, read docstrings for purpose, analyze git log for ownership. Risk: over-automation creates low-quality docs.

5. **Obsidian Sync for remote teams?** Obsidian Sync is a paid service. Alternative: since .memory/ is in git, standard git workflow handles it. But real-time collaboration would benefit from Sync or a shared vault.

---

## Appendix A: Quick Start (What the README Would Say)

```bash
# Install
pip install supermemory

# Initialize in your project
cd your-project
supermemory init

# Set your identity
supermemory whoami yourname

# Let your agent discover the codebase
supermemory systems discover

# Open in Obsidian (optional)
# Open Obsidian → "Open folder as vault" → select .memory/

# Start coding with your AI agent — it will read .memory/ automatically
```

---

## Appendix B: Migration from Existing Tools

### From Claude Code MEMORY.md

Move insights from `~/.claude/projects/*/memory/MEMORY.md` into appropriate .memory/ files:
- Architecture notes → systems/
- Bug workarounds → gotchas/
- Preferences → people/{me}.md

### From Beads Close Reasons

Run `bd list -s closed --json` and identify beads with substantial close_reasons. Manually promote to gotchas/ or decisions/ with `beads: [id]` backlinks.

### From docs/ or wiki

Move architectural docs to systems/, research docs to research/, ADRs to decisions/. Add frontmatter to each.
