# sigma-mem

Persistent agent teams that learn across sessions — using nothing but markdown files.

sigma-mem is a HATEOAS-navigated memory system for AI agents, built as an MCP server. It gives Claude (or any LLM) persistent identity, team coordination, and self-navigating memory retrieval.

## What it does

**Personal memory** — Stores user preferences, project state, past decisions, and calibration across sessions using compressed notation. A HATEOAS state machine detects conversation context and surfaces only what's relevant.

**Team memory** — Agents have persistent identities with personal memory, shared team decisions, and expertise-weighted knowledge. Wake only the agents you need. Each session builds on the last.

**One-call boot** — An agent calls `recall("I'm tech-architect on sigma-review, reviewing auth")` and gets back everything: personal memory, team decisions, patterns, roster, and teammates. No multi-step setup.

**Dream consolidation** — A four-phase memory maintenance cycle that deduplicates entries, prunes stale research, promotes tentative beliefs to confirmed, and verifies index integrity. Runs as a dry-run by default; apply changes explicitly.

## How it works

sigma-mem exposes memory as a navigable state machine via MCP:

```
recall("working on prompt-coach")
  -> state: project_work
  -> core memory + project context
  -> available: get_project, get_decisions, log_decision, get_failures, log_failure,
                search_memory, store_memory, check_integrity, get_meta

recall("I'm tech-architect on sigma-review, reviewing code")
  -> state: team_work
  -> core memory + agent boot (personal memory + team decisions + roster + teammates)
  -> available: get_roster, get_team_decisions, get_team_patterns, get_agent_memory,
                wake_check, validate_system, store_team_decision, search_team_memory,
                store_agent_memory, store_team_pattern,
                get_project, get_decisions, get_failures, get_patterns,
                search_memory, store_memory, check_integrity, get_meta
```

States: `idle`, `project_work`, `team_work`, `correcting`, `debugging`, `returning`, `reviewing`, `philosophical`

Each state unlocks different actions. The gateway detects context using weighted keyword scoring and surfaces the right memory with the right tools. Four actions (`search_memory`, `store_memory`, `check_integrity`, `get_meta`) are available in every state.

## Key concepts

- **HATEOAS navigation** — Memory files contain `-> action` links. Follow them to navigate. The state machine advertises available actions after every call.
- **Compressed notation** — `C[detects perf, honest>polish, probes|3|26.3]` stores what would take a paragraph in one line. Optimized for LLM token efficiency.
- **Anti-memories** — `![developer(leader learning to build)]` explicitly stores what is NOT true, preventing hallucinated beliefs.
- **Integrity checks** — Checksums, confidence markers (`~` = tentative), and promotion lifecycle (observed once -> confirmed across sessions).
- **Expertise-weighted decisions** — Team decisions carry attribution: who decided, from which domain, with dissenting context preserved.
- **Dream consolidation** — Four-phase cycle: consolidate (merge duplicates), prune (expire stale R[] entries, remove resolved corrections), reorganize (promote C~[]->C[] beliefs, detect patterns), index (verify checksums and structural integrity). Scoped to personal memory, a specific team, or all.

## ΣComm notation

sigma-mem stores and retrieves memory using ΣComm, a compressed notation designed for LLM token efficiency. Instead of verbose prose, agents read and write structured shorthand:

```
C[detects perf, honest>polish, probes|3|26.3]     # confirmed belief, 3 observations, since March
C~[prefers-TDD|1|26.4]                             # tentative belief, 1 observation
¬[developer(leader learning to build)]              # anti-memory: explicitly NOT true
R[api-latency-p99=120ms|source:grafana|26.4.1]     # research entry with source and date
```

Agent-to-agent messages use the same notation with status codes and action advertisements:

```
✓ auth-review: jwt-expiry-no-validate(!), pwd-md5>bcrypt |¬ session-mgmt |→ fix-jwt, fix-hash |#2
! test-suite: 14/20 pass, 6 fail in auth-module |→ need-auth-fix-first |#6-fail
```

Key symbols: `|` separator, `>` preference, `→` leads-to/available actions, `¬` explicitly NOT, `!` critical, `~` tentative, `#N` item count (checksum).

The full specification including inbox infrastructure, workspace conventions, and a codebook for agent system prompts is in [docs/sigma-comm-protocol.md](docs/sigma-comm-protocol.md). For a human-readable decoder of memory file notation, see [docs/notation-reference.md](docs/notation-reference.md).

## Actions by state

| State | Context-specific actions |
|-------|------------------------|
| `idle` | `get_project`, `get_decisions`, `get_corrections`, `get_user_model`, `get_conversations`, `verify_beliefs`, `dream`, team read actions |
| `project_work` | `get_project`, `get_decisions`, `log_decision`, `get_failures`, `log_failure` |
| `team_work` | `get_roster`, `get_team_decisions`, `get_team_patterns`, `get_agent_memory`, `wake_check`, `validate_system`, `store_team_decision`, `search_team_memory`, `store_agent_memory`, `store_team_pattern`, `get_project`, `get_decisions`, `get_failures`, `get_patterns` |
| `correcting` | `get_corrections`, `log_correction`, `update_belief` |
| `debugging` | `get_project`, `get_failures`, `log_failure` |
| `returning` | `full_refresh`, `verify_beliefs`, `dream` |
| `reviewing` | `get_decisions`, `get_patterns`, `get_conversations`, `get_team_decisions`, `dream` |
| `philosophical` | `get_user_model`, `get_patterns` |
| *all states* | `search_memory`, `store_memory`, `check_integrity`, `get_meta` |

## Installation

Not yet on PyPI. The quickest route is [uv](https://docs.astral.sh/uv/), which runs the server in an isolated environment and pulls in [hateoas-agent](https://github.com/coloradored13/hateoas-agent) from GitHub automatically:

```bash
claude mcp add sigma-mem --scope user -- uvx --from git+https://github.com/coloradored13/sigma-mem sigma-mem
```

Or install into an existing environment:

```bash
pip install git+https://github.com/coloradored13/sigma-mem.git
```

Python 3.11+.

## Usage

### As an MCP server

sigma-mem runs as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server. MCP is an open standard for connecting LLMs to external tools — the LLM client discovers available tools at runtime and calls them through the protocol, rather than having tools hardcoded into the application.

sigma-mem uses stdio transport: the MCP client (e.g., Claude Code) spawns the `sigma-mem` process and communicates over stdin/stdout. The server exposes `recall` as the gateway tool. After each call, the available tools update based on the detected state — so an LLM in `team_work` state sees team actions, while one in `correcting` state sees belief-update actions.

To connect from Claude Code, use the `claude mcp add` command from [Installation](#installation). If you installed with pip instead, `claude mcp add sigma-mem --scope user -- sigma-mem` works as long as `sigma-mem` is on your PATH.

Once configured, the LLM can call `recall("context description")` as a tool. The server detects the conversation context, returns relevant memories, and advertises the next set of available actions.

### Multi-agent access

MCP servers are session-level infrastructure — every agent in a Claude Code session shares access to the same MCP tools. When you spawn agents (via the Agent tool), they inherit the parent session's MCP connections automatically.

This means a multi-agent team can coordinate through sigma-mem without any extra wiring:

```
Claude Code session starts
  └─ spawns sigma-mem process (stdio)

User starts a review
  └─ lead agent calls recall("starting review of auth module")
      └─ sigma-mem returns core memory + project context
  └─ lead spawns tech-architect agent
      └─ tech-architect calls recall("I'm tech-architect on sigma-review, reviewing auth")
          └─ sigma-mem detects team_work state, returns agent boot package
          └─ tech-architect now has: personal memory, team decisions, roster, teammates
  └─ lead spawns product-strategist agent
      └─ same pattern — each agent boots with its own identity and shared team context
```

No agent needs to know how sigma-mem is connected. They call `recall()` like any other tool, and the state machine handles context detection and memory routing.

### Security model

sigma-mem trusts all connected MCP clients (inherent to stdio transport). File access is restricted to the configured memory and teams directories via path validation, but there is no authentication layer. Do not expose the server to untrusted clients.

### Memory directory structure

```
~/.claude/memory/          # personal memory
  MEMORY.md                # core identity (always loaded)
  projects.md              # project state
  decisions.md             # past decisions
  corrections.md           # what was wrong and fixed
  patterns.md              # cross-cutting observations
  ...

~/.claude/teams/           # team memory
  {team-name}/
    shared/
      roster.md            # who's on the team, domains, wake-for rules
      decisions.md         # expertise-weighted team decisions
      patterns.md          # cross-agent observations
    agents/
      {agent-name}/
        memory.md          # personal identity, findings, calibration
```

### Custom directories

```bash
sigma-mem --memory-dir /path/to/memory --teams-dir /path/to/teams
# or
SIGMA_MEM_DIR=/path/to/memory SIGMA_TEAMS_DIR=/path/to/teams sigma-mem
```

Both directories are created on first write. To seed a team by hand, create `{teams-dir}/{team}/shared/roster.md` with one line per agent (`agent-name |domain: a,b,c |wake-for: x,y`) and an empty `{teams-dir}/{team}/agents/{agent-name}/` folder per agent. The [sigma](https://github.com/coloradored13/sigma) Claude Code plugin does this for you with `/sigma-setup`.

## Architecture

Five modules, ~2,800 lines:

- `machine.py` — Declarative HATEOAS state machine (states, actions, handler bindings)
- `handlers.py` — All read/write operations for personal and team memory
- `dream.py` — Memory consolidation: dedup, prune, reorganize, and index verification
- `integrity.py` — Checksums, confidence detection, anti-memory verification
- `server.py` — MCP server entry point

Run the suite with `pytest tests/`.

Built on [hateoas-agent](https://github.com/coloradored13/hateoas-agent) for state machine and MCP serving.

## License

Apache 2.0 — see [LICENSE](LICENSE) for details.