amem

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.
No more repeating yourself. Every conversation starts where the last one left off.

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

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:

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

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

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

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

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

npx @aman_asmuei/amem

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

Maintenance tools

All tools return both human-readable text (content) and machine-readable JSON (structuredContent) with validated outputSchema.

Example: Storing a memory

memory_store({
  content: "Never use 'any' type — always define proper interfaces",
  type: "correction",
  tags: ["typescript", "types"],
  confidence: 1.0
})

Stored correction memory (a1b2c3d4). Confidence: 1. Tags: [typescript, types]. Total memories: 42.

Example: Recalling memories

memory_recall({ query: "TypeScript best practices", limit: 5 })

Found 2 memories for "TypeScript best practices":

1. [correction] Never use 'any' type — always define proper interfaces
   Score: 0.892 | Confidence: 100% | Age: 2d ago | Tags: [typescript, types]

2. [pattern] User prefers strict TypeScript with no implicit any
   Score: 0.756 | Confidence: 85% | Age: 5d ago | Tags: [typescript]

Example: Loading context for a task

memory_context({ topic: "authentication system", max_tokens: 2000 })

## Context for: authentication system

### Corrections
- Never store JWT secrets in environment variables (100% confidence)

### Decisions
- Chose OAuth2 + PKCE for the auth flow (90% confidence)

### Topology
- Auth module is in src/auth/, middleware in src/middleware/auth.ts (85% confidence)

Example: Batch extraction

Your AI can extract multiple memories from a single conversation:

memory_extract({
  memories: [
    { content: "Don't mock the DB in integration tests", type: "correction", tags: ["testing"], confidence: 1.0 },
    { content: "Chose event sourcing for audit trail", type: "decision", tags: ["architecture"], confidence: 0.9 }
  ]
})

Extraction complete: 2 stored, 0 reinforced.
Total memories: 44.

  + Stored [correction]: "Don't mock the DB in integration tests" (a1b2c3d4)
  + Stored [decision]: "Chose event sourcing for audit trail" (e5f6g7h8)

Example: Forgetting memories

Delete by ID or by query (with a safety confirmation step):

memory_forget({ query: "old project", confirm: false })

Found 3 memories matching "old project". Preview:
1. [a1b2c3d4] Old project used Express.js
2. [e5f6g7h8] Old project had no tests

Call again with confirm=true to delete these.

Resources & Prompts

MCP Resources

amem exposes 4 resources that AI clients can read proactively at the start of a conversation:

MCP Prompts

amem provides 2 prompts that teach AI clients how to use the memory system effectively:

CLI

amem includes a standalone command-line interface for managing memories directly:

amem-cli recall "authentication"      # Search memories semantically
amem-cli stats                        # Show statistics with visual bars
amem-cli list                         # List all memories
amem-cli list --type correction       # Filter by type
amem-cli export                       # Export to stdout as markdown
amem-cli export --file memories.md    # Export to file
amem-cli forget abc12345              # Delete by ID (short IDs supported)

Configuration

amem works out of the box with zero configuration. For advanced use:

Project scoping is automatic — amem detects your git repo name. Override with AMEM_PROJECT:

{
  "mcpServers": {
    "amem": {
      "command": "amem",
      "env": { "AMEM_PROJECT": "my-project" }
    }
  }
}

Technical Details

Stack

MCP Best Practices

amem follows the MCP best practices checklist:

• All 9 tools use server.registerTool() with title, description, inputSchema, outputSchema, and annotations
• All tool handlers wrapped in try-catch with isError: true on failures
• All Zod schemas use .strict() to reject unknown fields
• All error messages are actionable (suggest next steps)
• Server name follows convention: amem-mcp-server
• Transport: stdio (correct for local-first tool)
• Logging to stderr (not stdout)
• Graceful shutdown on SIGINT/SIGTERM

Architecture

src/
├── index.ts        Entry point — server, prompts, resources, transport
├── tools.ts        10 MCP tools with annotations, validation, structured output
├── schemas.ts      Zod output schemas for structuredContent responses
├── memory.ts       Scoring engine, conflict detection, recall algorithm
├── database.ts     SQLite schema, prepared statements, CRUD interface
├── embeddings.ts   Local embedding pipeline + cosine similarity
└── cli.ts          Standalone CLI for direct memory management

~1,300 lines of TypeScript. Clean separation of concerns, no circular dependencies.

FAQ

Contributing

Contributions are welcome! Here's how to get involved.

Development setup

git clone https://github.com/amanasmuei/amem.git
cd amem
npm install
npm run build
npm test

Scripts

Project structure

amem/
├── src/
│   ├── index.ts        # MCP server entry point, prompts, resources
│   ├── tools.ts        # 7 tool definitions with validation & error handling
│   ├── memory.ts       # Scoring engine, conflict detection, recall
│   ├── database.ts     # SQLite schema, prepared statements, CRUD
│   ├── embeddings.ts   # Local embedding pipeline + cosine similarity
│   └── cli.ts          # Standalone CLI
├── tests/
│   ├── database.test.ts
│   ├── embeddings.test.ts
│   ├── memory.test.ts
│   └── tools.test.ts
├── .github/
│   └── workflows/
│       ├── ci.yml      # Test on push/PR (Node 18/20/22)
│       └── publish.yml # Publish to npm on GitHub Release
├── package.json
├── tsconfig.json
└── vitest.config.ts

Making changes

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes
4. Ensure the build is clean: npm run build
5. Ensure all tests pass: npm test
6. Commit and push your branch
7. Open a Pull Request against main

CI/CD

GitHub Actions runs automatically on every push and pull request:

• CI workflow (ci.yml) — builds and tests against Node.js 18, 20, and 22 on Ubuntu
• Publish workflow (publish.yml) — triggered on GitHub Release, builds, tests, and publishes to npm with --access public

All PRs must pass the CI pipeline before merging.

Reporting issues

Found a bug or have a feature idea?

• Bug reports: Open an issue with steps to reproduce, expected vs. actual behavior, and your Node.js version
• Feature requests: Open an issue describing the use case and how it would improve the memory system
• Questions: Start a discussion (or open an issue)

Roadmap

• 8 MCP tools with full annotations, validation, and error handling
• Semantic search with local embeddings (graceful fallback to keywords)
• Smart conflict detection and deduplication
• Memory evolution (related memories reinforce each other)
• CLI for direct memory management
• MCP prompts and resources for proactive context
• Published on npm
• outputSchema + structuredContent for machine-readable tool responses
• Proactive context injection (memory_inject tool)
• Evaluation suite (10 standardized eval questions)
• Memory consolidation — merge, prune, promote (the first MCP memory server with this)
• Project scoping — auto-detect project, scope memories global vs project
• Memory verification against filesystem
• Knowledge graph with entity relationships
• Team memory (shared context across developers)