# Super Memory

Persistent shared knowledge layer for AI coding agents.

AI coding agents (Claude Code, Cursor, Aider) suffer from session amnesia. Every new session starts cold — rediscovering architecture, re-exploring codebases, repeating mistakes. **Super Memory** fixes this with a `.memory/` directory that any agent can read and write.

## How It Works

A `.memory/` directory in your repo holds structured markdown files with YAML frontmatter:

- **systems/** — Architecture docs for each subsystem (committed)
- **decisions/** — Architectural Decision Records (committed)
- **gotchas/** — Known pitfalls and bug patterns (committed)
- **research/** — Investigation findings (committed)
- **people/** — Per-person context and ownership (committed)
- **sessions/** — Session summaries (gitignored)
- **scratch/** — Working memory during sessions (gitignored)

Agents read these on session start (warmup), write discoveries during work, and commit knowledge at session end (cooldown).

## Quick Start

```bash
# Install
pip install atlas-memory

# Initialize in your project
cd your-project
atlasmemory init

# Set your identity
atlasmemory whoami yourname

# Auto-discover codebase systems
atlasmemory systems discover

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

## Non-Interactive Init

```bash
atlasmemory init \
  --project "my-project" \
  --me mitch \
  --platform claude-code \
  --tracker beads \
  --obsidian \
  --auto-discover
```

## CLI Commands

```bash
atlasmemory init                              # Initialize .memory/
atlasmemory whoami [name]                     # Get/set identity
atlasmemory systems                           # List system docs
atlasmemory systems discover                  # Auto-discover modules
atlasmemory systems stale                     # Show stale docs
atlasmemory query --system auth               # Query by system tag
atlasmemory query --concern race-condition    # Query by concern tag
atlasmemory summary                           # Regenerate SUMMARY.md
atlasmemory health                            # Check memory health
atlasmemory check-conflict path/to/file.py    # Check DO NOT TOUCH claims
```

## Agent Platforms

Super Memory integrates with:

| Platform | What `init` Does |
|----------|-----------------|
| **Claude Code** (`--platform claude-code`) | Appends protocol to CLAUDE.md |
| **Cursor** (`--platform cursor`) | Appends protocol to .cursorrules |
| **Aider** (`--platform aider`) | Generates .aider.conf.yml |

## Obsidian Integration

Pass `--obsidian` to `atlasmemory init` to generate Obsidian vault config. Then open `.memory/` as an Obsidian vault for graph view, tag filtering, backlinks, and Dataview queries.

## Issue Tracker Integration

Super Memory complements (doesn't replace) issue trackers. Use `--tracker` with:
`beads`, `linear`, `github`, or `jira` to enable backlink fields in templates.

## Team Usage

1. Each team member runs `atlasmemory whoami theirname`
2. Memory files are committed to git and shared
3. Person files track who's working on what (agents check "DO NOT TOUCH" sections)
4. Sessions and scratch stay local (gitignored)

## License

MIT
