Amem

<div align="center">

Give your AI a memory it never forgets

amem (Aman's Memory) gives your AI persistent memory — so it remembers your preferences, decisions, and corrections forever.<br/>No more repeating yourself. Every conversation starts where the last one left off.

Get Started · How It Works · Tools · Resources & Prompts · CLI · FAQ · Contributing

</div>

---

The Problem

Every time you start a new conversation with an AI coding assistant, it starts from zero. It doesn't know:

- That you told it three times not to use any in TypeScript
- That your team chose PostgreSQL over MongoDB last month (and why)
- That you prefer functional style, early returns, and pnpm
- Where your auth module lives, or how your project is structured

You end up repeating yourself. Every. Single. Time.

The Solution

amem is a memory layer that plugs into any AI tool — Claude Code, Cursor, Windsurf, or anything that speaks MCP. It remembers what matters and surfaces it automatically.

You: "Don't use any type in TypeScript"
amem saves this as a correction (highest priority).

  Next conversation — or next month — your AI already knows.

---

What Gets Remembered

amem organizes memories into six types, ranked by importance:

| Priority | Type | What it captures | Example |
|:--------:|------|-----------------|---------|
| 1.0 | Correction | Mistakes to never repeat | "Don't mock the database in integration tests" |
| 0.85 | Decision | Architectural choices + why | "Chose Postgres over MongoDB for ACID compliance" |
| 0.7 | Pattern | Coding style & habits | "Prefers early returns over nested conditionals" |
| 0.7 | Preference | Tool & workflow choices | "Uses pnpm, not npm" |
| 0.5 | Topology | Where things are | "Auth module lives in src/auth/, uses JWT" |
| 0.4 | Fact | General project knowledge | "API uses REST, launched January 2025" |

Corrections always surface first. They're the "never do this" rules your AI should always follow.

---

Get Started

Step 1: Install

You need Node.js 18 or higher. Then:

npm install -g @aman_asmuei/amem

That's it. amem is now installed on your machine.

Step 2: Connect your AI tool

<details>
<summary><strong>Claude Code (CLI)</strong></summary>

One-liner:

claude mcp add amem -- npx -y @aman_asmuei/amem

Or manually add to ~/.claude/settings.json:

{
  "mcpServers": {
    "amem": {
      "command": "npx",
      "args": ["-y", "@aman_asmuei/amem"]
    }
  }
}

Restart Claude Code. You'll see 9 memory tools, 4 resources, and 2 prompts available.

</details>

<details>
<summary><strong>Cursor</strong></summary>

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "amem": {
      "command": "amem"
    }
  }
}

Restart Cursor.

</details>

<details>
<summary><strong>Windsurf</strong></summary>

Add to your MCP configuration:

{
  "mcpServers": {
    "amem": {
      "command": "amem"
    }
  }
}

</details>

<details>
<summary><strong>Any other MCP client</strong></summary>

amem speaks standard Model Context Protocol over stdio. Point your client to:

npx @aman_asmuei/amem

</details>

Step 3: Start talking

That's it. Your AI now has memory tools. Ask it to remember something:

> "Remember that we use Tailwind with a custom theme in this project."

Next conversation, ask:

> "What CSS framework do we use?"

It knows.

---

How It Works

┌──────────────────────────────────┐
│          Your AI Tool            │
│   Claude · Cursor · Windsurf     │
└──────────┬───────────────────────┘
           │
     MCP Protocol (stdio)
           │
┌──────────▼───────────────────────┐
│       amem-mcp-server            │
│                                  │
│  9 Tools · 4 Resources · 2 Prompts
│                                  │
│   Store → Score → Deduplicate    │
│   Recall → Rank → Surface       │
│                                  │
│   ┌────────────────────────────┐ │
│   │  SQLite + Local Embeddings │ │
│   │  ~/.amem/memory.db         │ │
│   └────────────────────────────┘ │
└──────────────────────────────────┘

Everything stays on your machine. No cloud. No API keys. No data leaving your laptop.

Smart ranking

Every memory gets a composite score:

score = relevance × recency × confidence × importance

- Relevance — How closely the memory matches what you're working on (cosine similarity via local embeddings, with keyword fallback)
- Recency — Exponential decay (0.995^hours) — recent memories score higher, old ones gradually fade
- Confidence — Memories confirmed multiple times score higher (0.0 to 1.0)
- Importance — Type-based weight: Corrections (1.0) > Decisions (0.85) > Patterns (0.7) > Facts (0.4)

Conflict detection

Store a memory that contradicts an existing one? amem catches it:

- >85% similar but different — Flags the conflict, updates the existing memory's confidence
- >80% similar and agreeing — Reinforces the existing memory (+0.1 confidence)
- 60-80% related — Touches related memories to keep them fresh
- No match — Stores as new

Memory evolution

When you store a new memory, related existing memories (60-80% similarity) get reinforced automatically — their access timestamps update, keeping your knowledge base connected and current.

Memory consolidation

Over time, memories accumulate — duplicates, stale facts, forgotten preferences. amem is the first MCP memory server with built-in consolidation:

- Merge — Near-duplicate memories (>85% similarity) are combined. The higher-confidence version is kept and boosted.
- Prune — Stale memories (>60 days inactive, low confidence, rarely accessed) are removed. Corrections are never pruned.
- Promote — Memories accessed 5+ times with low confidence get promoted to 90% confidence.
- Health score — After consolidation, you get a 0-100 health score (signal-to-noise ratio).

Use memory_consolidate with confirm: false to preview, then confirm: true to execute.

Project scoping

Memories know where they apply:

- Global — Corrections, preferences, and patterns follow you everywhere (e.g., "Don't use any in TypeScript")
- Project-scoped — Decisions, topology, and facts stay with their project (e.g., "Auth module is in src/auth/")

Project is auto-detected from AMEM_PROJECT env var or your git repo name. When recalling, amem returns global memories + current project memories — never leaking another project's context.

---

Tools

amem gives your AI 9 tools it can use during conversation. All tools include:

- Strict input validation with Zod schemas (invalid inputs are rejected with clear error messages)
- Tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so clients understand tool behavior
- Structured error handling — errors return isError: true with actionable suggestions

Core tools

…