Engram Tools

Shared memory for AI coding agents. Engram lets MCP-compatible agents store what they learn, recall team knowledge, transfer lessons across repos, and report whether recalled memories actually helped.

What Works Today

• MCP server package: engram-tools
• HTTP API for hosted or custom agent integrations
• Persistent memories by workspace and repo
• engram_start for one-call session setup + smart context loading
• engram_smarter for task-specific context loading when switching tasks
• engram_store, engram_recall, engram_report_outcome, engram_get_context, engram_skill, and engram_setup
• Outcome-based confidence updates
• Plan limits and daily API usage metering
• Stripe checkout/webhook plan updates
• Basic team dashboard for usage, limits, and recent memories
• PostgreSQL + pgvector semantic search when VOYAGE_API_KEY is configured
• Text-search fallback when embeddings are unavailable

Quick Start

npx engram-tools --setup engram_your_api_key

The setup command writes MCP config for Claude Code, Cursor, Gemini CLI, Codex, OpenCode, and VS Code/Copilot project config when possible. For Claude Code, it also writes optional slash-command aliases for convenience.

After setup, restart your AI tool or start a new session. Most MCP clients load servers only at session startup. Start every client the same way: call engram_start once with project, repo, stack, role, market, and task.

If the conversation was compacted, summarized, resumed, or the agent feels prior context is incomplete, call engram_start again before continuing. If the agent is mid-session and only needs focused recovery, call engram_smarter with the current task context.

Manual MCP config:

{
  "mcpServers": {
    "engram": {
      "command": "npx",
      "args": ["-y", "engram-tools"],
      "env": {
        "ENGRAM_API_KEY": "engram_your_api_key",
        "ENGRAM_API_URL": "https://api.engram.tools"
      }
    }
  }
}

Core Tools

engram_start

Start or recover a session in one call. This loads setup guidance, the Engram operating contract, and the most relevant memories/skill guides. Use it at the beginning of a session, after compaction/resume, when entering a repo, or when task context changes.

{
  "project": "HouseCompass",
  "repo": "housecompass.uk",
  "role": "frontend product engineer",
  "market": "UK property",
  "task": "build the listing detail page",
  "stack": ["Next.js", "TypeScript", "PostgreSQL"]
}

engram_smarter

Load task-specific memories and matching skill guides in one call. Use this after engram_start, when switching tasks, or when recovering focused context mid-session.

{
  "context": "Next.js 16 + Prisma signup bug, fixing API key setup",
  "repo": "engram",
  "include_skills": true
}

engram_cross_pollinate

Find reusable lessons from other repos in the same workspace.

{
  "target_repo": "engram",
  "context": "Stripe webhook tier updates and signup reliability"
}

engram_store

Save a convention, pattern, gotcha, solution, architecture note, or dependency quirk.

engram_recall

Search memories by semantic query, repo, type, or tags.

engram_report_outcome

Report whether a recalled memory helped. This updates confidence and improves future ranking.

HTTP API

Hosted API base:

https://api.engram.tools

Useful endpoints:

• POST /api/v1/start
• POST /api/v1/smarter
• POST /api/v1/cross-pollinate
• POST /api/v1/store
• POST /api/v1/recall
• POST /api/v1/report
• POST /api/v1/context
• POST /api/v1/skill
• POST /api/v1/setup
• GET /api/v1/capabilities

All private endpoints require:

Authorization: Bearer <ENGRAM_API_KEY>

Local Development

npm install
npm run db:setup
npm run dev:http

Environment:

DATABASE_URL=postgresql://...
ENGRAM_API_KEY=engram-dev-key-001
VOYAGE_API_KEY=optional

Run verification:

npm run typecheck
npm run build
npm run test:product

The product smoke test stores memories, calls /api/v1/smarter, and verifies /api/v1/cross-pollinate.

Status

Engram is in beta. The core memory, smarter context, cross-repo transfer, outcome-learning, hosted limits, API metering, Stripe plan updates, and basic dashboard flows are implemented. Scale-plan items such as SSO/SAML, self-hosted packaging, and SLA terms are handled as custom rollout work.

License

MIT