> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sense-lab.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Setup

> Give your AI coding agents persistent, shared memory in under 2 minutes.

Add AMFS to Cursor, Claude Code, or any MCP client. Your agents get persistent memory that compounds across sessions, machines, and teammates.

## Cursor

Add to `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global):

```json theme={null}
{
  "mcpServers": {
    "amfs": {
      "command": "uvx",
      "args": ["amfs-mcp-server"],
      "env": {
        "AMFS_HTTP_URL": "https://amfs-login.sense-lab.ai",
        "AMFS_API_KEY": "<your-api-key>"
      }
    }
  }
}
```

<Tip>
  Copy the ready-made snippet from your [AMFS Dashboard → Agents page](https://amfs-login.sense-lab.ai). The **MCP Connection Card** has your URL and key pre-filled.
</Tip>

## Claude Code

Add to `~/.claude/claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "amfs": {
      "command": "uvx",
      "args": ["amfs-mcp-server"],
      "env": {
        "AMFS_HTTP_URL": "https://amfs-login.sense-lab.ai",
        "AMFS_API_KEY": "<your-api-key>"
      }
    }
  }
}
```

## Verify

Restart your IDE after saving the config. Ask the agent to run `amfs_stats()` — if it returns a response, you're connected.

***

## What Your Agents Get

Once connected, agents have 20+ tools across five categories:

**Identity & Context**

| Tool                | What it does                                             |
| :------------------ | :------------------------------------------------------- |
| `amfs_set_identity` | Name this agent session (e.g. `"checkout-fixer"`)        |
| `amfs_briefing`     | Get a compiled knowledge digest — what matters right now |

**Read & Write**

| Tool                       | What it does                                                         |
| :------------------------- | :------------------------------------------------------------------- |
| `amfs_read` / `amfs_write` | Read and write versioned memory entries                              |
| `amfs_search`              | Filter by entity, confidence, agent, time range                      |
| `amfs_retrieve`            | Natural language search with semantic + recency + confidence ranking |
| `amfs_list` / `amfs_stats` | Browse entries and get an overview                                   |
| `amfs_history`             | Version history of any entry                                         |
| `amfs_graph_neighbors`     | Explore the knowledge graph                                          |

**Agent Brain**

| Tool              | What it does                               |
| :---------------- | :----------------------------------------- |
| `amfs_recall`     | Recall your own memories                   |
| `amfs_my_entries` | List everything you've written             |
| `amfs_read_from`  | Read from another agent's memory (tracked) |

**Decision Traces**

| Tool                  | What it does                                          |
| :-------------------- | :---------------------------------------------------- |
| `amfs_record_context` | Capture tool results, user choices, and external data |
| `amfs_commit_outcome` | Snapshot the full decision trace                      |
| `amfs_explain`        | Inspect the causal chain                              |

**Timeline**

| Tool            | What it does                   |
| :-------------- | :----------------------------- |
| `amfs_timeline` | Browse the git-style event log |

***

## Agent Identity

Agents should call `amfs_set_identity` at the start of every session:

```text theme={null}
amfs_set_identity("checkout-agent", "Fixing retry logic")
```

Use **kebab-case role names** that persist across conversations:

| Good              | Bad                               |
| :---------------- | :-------------------------------- |
| `dashboard-agent` | `fix-button-color` (too specific) |
| `api-agent`       | `agent-1` (meaningless)           |

If `amfs_set_identity` isn't called, the MCP server auto-detects identity from the IDE environment (`cursor/<username>`, `claude-code/<username>`).

***

## AMFS Skill

Use this skill at the start of any session where AMFS MCP tools are connected. This skill covers the full session lifecycle: set identity, briefing, read/write, and commit outcome. Also use when storing decisions, retrieving past context, or referring to AMFS (agent memory) or persistent memory across sessions.

```markdown theme={null}
---
name: amfs
description: "Use this skill at the start of any session where AMFS MCP tools are connected. Covers the full session lifecycle: set identity, briefing, read/write, commit outcome. Also use when storing decisions, retrieving past context, or any mention of AMFS, agent memory, or persistent memory across sessions."
---

# AMFS Skill

Use this skill whenever AMFS MCP tools are available — reading context, storing decisions, or committing outcomes across sessions.

## Trigger conditions
- Starting any session where AMFS MCP is connected
- User asks to remember, store, or retrieve something
- After making a significant decision or completing meaningful work
- When context from a previous session may be relevant

## Session workflow (always follow this order)

1. **Set identity** — always first, every session. Use a stable kebab-case name that persists across conversations about the same domain.
   `amfs_set_identity("your-agent-name", "what you're doing this session")`
   Good names: `api-agent`, `infra-agent`, `dashboard-agent`
   Bad names: `fix-button` (too specific), `agent-1` (meaningless)

2. **Get briefing** — one call replaces many reads
   `amfs_briefing(entity_path="repo/module")`
   If briefing is empty, use `amfs_list` or `amfs_read` to pull specific keys.

3. **Work** — read before decisions, write after meaningful ones

4. **Commit** — always at session end, it's free
   `amfs_commit_outcome("task-ref", "success|minor_failure|failure")`

## Entity path conventions
Use hierarchical `{project}/{module}` paths to scope knowledge. Avoid generic paths like `project` or `app` — they become unsearchable.

Examples:
- `myapp/auth` — authentication module
- `myapp/api` — API layer
- `myapp/checkout` — checkout service
- `user/context` — personal or cross-project context
- `user/preferences` — working style, communication preferences

## Key naming conventions
- `pattern-` reusable patterns
- `risk-` known bugs or blockers
- `decision-` architectural or strategic choices
- `task-summary-` what was done and why
- `action-` log of actions taken

## Cost model
- Read = 1 op (`amfs_read`, `amfs_search`, `amfs_list`, `amfs_briefing`)
- Write = 2 ops (`amfs_write`, `amfs_record_context`)
- Commit = free (never skip)

Prefer `amfs_briefing` over multiple individual reads — one briefing returns compiled, ranked knowledge for an entity.

## What to write
- Decisions with rationale (why, not just what)
- Risks or blockers discovered
- Patterns worth reusing
- Task summaries after meaningful work
- User decisions that affect direction

## What to skip
- Trivial changes (typos, renames, comments)
- Anything recomputable from the codebase in seconds
- One-sentence observations — batch related ones into a single richer entry

## Memory types
- `fact` — stable, verified knowledge (default)
- `belief` — hypothesis or unverified observation, use confidence < 0.9
- `experience` — action log, decays slower, good for what was done and why

## Confidence guidelines
- `1.0` — verified, tested in production
- `0.7–0.9` — high confidence, not yet verified
- `0.4–0.6` — hypothesis, needs validation
- `< 0.4` — speculative, early signal

## Known issues
- `amfs_commit_batch` may throw a CausalTagger session_id error — use individual `amfs_write` calls instead
- `amfs_briefing` returns empty on new stores until the Memory Cortex compiles digests (async)
```

***

## How Knowledge Compounds

```text theme={null}
Machine A (Cursor / Bruno):
  → Reviews checkout-service PR
  → amfs_write("myapp/checkout", "risk-race-condition", "...")
  → amfs_commit_outcome("PR-456", "minor_failure")

Machine B (Claude Code / Alice):
  → Starts working on checkout-service
  → amfs_briefing(entity_path="myapp/checkout")
  → Sees Bruno's risk signal with boosted confidence
  → Avoids the same issue
```

***

## Pinning a Version

To pin to a specific MCP server version:

```json theme={null}
"args": ["amfs-mcp-server@0.2.3"]
```

***

## Troubleshooting

| Problem                        | Fix                                                                                                                       |      |
| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------ | ---- |
| `uvx: command not found`       | Install [uv](https://docs.astral.sh/uv/): \`curl -LsSf [https://astral.sh/uv/install.sh](https://astral.sh/uv/install.sh) | sh\` |
| Agent doesn't use memory tools | Add the [agent rules file](#agent-rules) to your project                                                                  |      |
| `401 Unauthorized`             | Check your API key in Dashboard → Settings → API Keys                                                                     |      |
| `403 Scope Denied`             | Your key doesn't have permission for that entity path                                                                     |      |