Agent Engrams

Table of contents

• Introduction
• Architecture
• On-disk layout
• Quick Start
• Tools
• Configuration Reference
• Engram Format
• Transport Modes
• Development
• License

Introduction

What this is. Agent Engrams MCP is a Model Context Protocol server that gives coding agents a durable, shared memory for transferable engineering knowledge. Agents store lessons as structured markdown documents called engrams on your machine; the server indexes them with embeddings so agents can search by meaning, not just filenames. Your IDE (Cursor, VS Code, or any MCP-aware client) talks to the server over stdio; the server reads and writes files locally and calls an OpenAI-compatible embedding API when indexing and searching.

Why it matters. Agent sessions are short and context windows are finite. Without a memory that survives across tasks and projects, every session starts from zero: the same debugging tricks, API quirks, and architectural lessons get rediscovered-or missed-again and again. A shared engram store turns one-off insights into reusable knowledge: your agent (and others using the same store) can recall what already worked before inventing a new dead end.

The learning flywheel. The engram system is designed around a loop that gets stronger the more it is used honestly:

1. Recall - Before diving into a non-trivial task, search the store. Prior work may already answer the question.
2. Learn - During the task, notice transferable patterns (would this help on a different project?). That is engram-worthy.
3. Write - Capture those insights in structured engrams so the next recall is richer.

Each high-quality write makes the next search more useful; that encourages more search, which surfaces more opportunities to learn and write. That self-reinforcing loop is the flywheel effect. It stalls if the store fills with noise (low-quality writes), if agents skip search (duplicate effort), or if everything is written indiscriminately (diluted results). Quality beats quantity.

flowchart LR
    Recall["Recall<br/>Search engrams<br/>before you act"]
    Learn["Learn<br/>Spot transferable<br/>knowledge"]
    Write["Write<br/>Capture durable<br/>engrams"]

    Recall --> Learn
    Learn --> Write
    Write -->|"Richer store →<br/>better recall"| Recall

The flywheel is a habit, not a one-time setup: the MCP server is the machinery that stores, embeds, and retrieves engrams so that loop can run every day.

Architecture

graph LR
    IDE["IDE<br/>(Cursor · VS Code)"]
    MCP["agent-engrams-mcp<br/>MCP Server"]
    FS["Local store<br/>ENGRAMS_DIR"]
    EMB["Embedding Model<br/>(OpenAI-compatible API)"]

    IDE -- "stdio / JSON-RPC" --> MCP
    MCP -- "read / write under<br/>.../docs/*.md" --> FS
    MCP -- "POST /v1/embeddings" --> EMB

The IDE spawns the MCP server as a child process. When an agent writes or searches engrams, the server reads and writes markdown under the store's docs/ folder and calls an OpenAI-compatible embedding endpoint to build query vectors and score matches.

On-disk layout

ENGRAMS_DIR (and the dir field in mcp.json) is the store root, not the folder that holds markdown directly. The server creates this layout on startup if it is missing:

If you previously set ENGRAMS_DIR to a path ending in /docs, that still works: the server treats it as a legacy docs-only path (root = parent directory, docs = that path).

Quick Start

Prerequisites

• Node.js 20+
• An OpenAI-compatible embedding API (local or remote). Examples: Ollama, LM Studio, vLLM, OpenAI.

1. Install

npm install -g agent-engrams-mcp

2. Configure your IDE

Pick your editor and paste the JSON block into the indicated file. Adjust the env values to match your embedding provider.

Cursor

Add to ~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json (per-project):

{
  "mcpServers": {
    "agent-engrams": {
      "command": "npx",
      "args": ["agent-engrams-mcp", "--stdio"],
      "env": {
        "ENGRAMS_DIR": "~/.config/agent-engrams-mcp",
        "EMBEDDER_DIMENSIONS": "512",
        "EMBEDDER_TYPE": "openai",
        "EMBEDDER_BASE_URL": "http://localhost:8000/v1",
        "EMBEDDER_API_KEY": "your-api-key",
        "EMBEDDER_MODEL": "Qwen3-Embedding-0.6B-4bit-DWQ"
      }
    }
  }
}

Visual Studio Code

Add to your VS Code settings (JSON):

{
  "mcp.servers": {
    "agent-engrams": {
      "command": "npx",
      "args": ["agent-engrams-mcp", "--stdio"],
      "env": {
        "ENGRAMS_DIR": "~/.config/agent-engrams-mcp",
        "EMBEDDER_DIMENSIONS": "512",
        "EMBEDDER_TYPE": "openai",
        "EMBEDDER_BASE_URL": "http://localhost:8000/v1",
        "EMBEDDER_API_KEY": "your-api-key",
        "EMBEDDER_MODEL": "Qwen3-Embedding-0.6B-4bit-DWQ"
      }
    }
  }
}

3. Restart your IDE

After saving the config, restart (or reload MCP servers) so the IDE picks up the new server. You should see agent-engrams listed among your MCP servers.

That's it - your agent now has persistent memory.

Tools

The server exposes three tools to the agent:

Three seed engram resources ship with the server to guide agents on writing and searching effectively.

Configuration Reference

All settings can be provided via environment variables (shown above in the IDE snippets), a JSON config file, or CLI arguments. Environment variables take precedence over the config file.

Environment Variables

Config File

If you prefer a config file over env vars, create ~/.config/agent-engrams-mcp/mcp.json:

{
  "dir": "~/.config/agent-engrams-mcp",
  "dimensions": 512,
  "provider": {
    "type": "openai",
    "model": "Qwen3-Embedding-0.6B-4bit-DWQ",
    "baseUrl": "http://localhost:11434/v1",
    "apiKey": "your-api-key"
  },
  "minSearchScore": 0.40
}

A starter file is included in the repo:

mkdir -p ~/.config/agent-engrams-mcp
cp mcp.json.example ~/.config/agent-engrams-mcp/mcp.json

Provider Examples

{
  "type": "openai",
  "model": "text-embedding-3-small",
  "baseUrl": "https://api.openai.com/v1",
  "apiKey": "sk-..."
}

{
  "type": "bedrock",
  "profile": "default",
  "region": "us-east-1",
  "model": "amazon.titan-embed-text-v2:0"
}

{
  "type": "ollama",
  "url": "http://localhost:11434",
  "model": "nomic-embed-text"
}

CLI Arguments

Override any setting when starting the server directly:

npm start -- --dir=/path/to/store-root --dimensions=768
npm start -- --provider='{"type":"openai","model":"text-embedding-3-small","baseUrl":"https://api.openai.com/v1","apiKey":"sk-..."}'

Engram Format

Engrams are markdown files with YAML frontmatter:

---
Category: debugging
Tags: async, testing, jest
Durability: permanent
Scope: universal
Agent: system
Date: 2024-01-01
Source: Task #123
---

# Title of the Engram

## Context

What situation triggered this learning? Include specific details.

## Insight

What was learned? What is the non-obvious part? Be specific.

## Application

**Trigger:** When to apply this knowledge
**Anti-trigger:** When NOT to apply this knowledge

## Supersedes

None

Transport Modes

Architecture

The application follows a clean architecture pattern with clear separation of concerns:

Core Components

• src/index.ts - Entry point with CLI argument parsing, config loading, and service instantiation
• src/mcp-server-service.ts - MCP server service that encapsulates server initialization and tool registration
• src/engram-service.ts - Application service layer for engram operations
• src/abstractions.ts - Interface definitions for external dependencies (file system, HTTP fetch)
• src/embedder.ts - Embedding provider implementations (OpenAI, Bedrock, Ollama)
• src/index-store.ts - Index management and search logic
• src/config.ts - Configuration loading and management
• src/frontmatter.ts - Markdown parsing and engram rendering

Dependency Injection

External dependencies are injected via interfaces:

• IFileSystem - File system operations (defaults to NodeFileSystem)
• IHttpFetch - HTTP fetch operations (defaults to createHttpFetch())

This enables easy mocking for unit tests.

Testability

The refactored code is designed for easy testing:

• No global state - all state is encapsulated within class instances
• All external dependencies are injectable via interfaces
• Test helpers provide easy setup for test instances
• Tests can run without network access or file system

Development

npm install
npm run build        # compile TypeScript
npm run typecheck    # type check only
npm run lint         # lint
npm run format       # check formatting

License

MIT