engram-tools

Engram

Memory for AI agent teams. Engram lets MCP-compatible agents recover after context compaction, recall relevant team knowledge, preserve durable learnings, transfer proven lessons across projects, 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_rehydrate for context-compaction recovery from the session journal
• 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

Create a free workspace, verify your email, and use the personal key in your setup email. Verify the same email again to recover your existing key. Invite teammates from the dashboard so each person receives their own key for the shared workspace.

npx engram-tools --setup engram_your_api_key

For an agent-driven install, keep the credential out of the command arguments and preview the selected client first:

export ENGRAM_API_KEY=engram_your_api_key
npx -y engram-tools@latest --setup --client codex --dry-run
npx -y engram-tools@latest --setup --client codex

Supported selectors are claude, cursor, gemini, antigravity, windsurf, opencode, codex, copilot, cline, roo, kiro, amazonq, goose, continue, and all. Aliases such as roo-code and amazon-q are accepted. The agent may run the command when its host grants shell and file access; workspace authorization and payment remain human-controlled.

The setup command writes MCP config for Claude Code, Cursor, Gemini, Antigravity, Codex, OpenCode, VS Code/Copilot, Cline, Roo Code, Kiro, Amazon Q Developer, Goose, and Continue when possible. Existing JSON, TOML, and YAML settings are preserved. For Claude Code, it also writes optional slash-command aliases for convenience. Copilot, Roo, Cline, and Continue receive user-scoped configurations as well as compatibility project configurations; Claude Code receives ~/.claude.json even when its CLI helper is unavailable. Engram also sends usage guidance during the MCP handshake, so entering a new repository does not require copying AGENTS.md. Client trust and tool-approval settings still apply.

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.

Verify the first useful memory

Tell your agent: “We are working on [project] with [stack]. Use Engram to recover the project context, then continue [task].” After a real task, ask it to preserve a durable decision or solved gotcha. In a new session, ask it to recover that decision before continuing. Check the workspace dashboard for activity and the stored memory. Installing alone does not create private project knowledge; the public bank is available immediately.

Setup scope

These are user-scoped defaults on the machine running setup. Compatibility project files are also refreshed in the current folder.

Client	Global connection
Claude Code	~/.claude.json
Cursor	~/.cursor/mcp.json
Gemini CLI	~/.gemini/settings.json
Antigravity	Existing shared, IDE and CLI config destinations under ~/.gemini/
Windsurf	~/.codeium/windsurf/mcp_config.json
OpenCode	~/.config/opencode/opencode.json
Codex	~/.codex/config.toml
Copilot / VS Code	~/.copilot/mcp-config.json and editor user-profile mcp.json
Cline	~/.cline/data/settings/cline_mcp_settings.json; compatibility config and installed legacy extension storage
Roo Code	Editor user-profile globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json
Kiro	~/.kiro/settings/mcp.json
Amazon Q	~/.aws/amazonq/mcp.json
Goose	~/.config/goose/config.yaml
Continue	~/.continue/mcpServers/engram.json

Setup discovers existing Code Insiders, VSCodium, Cursor and Windsurf user directories and named profiles. It respects COPILOT_HOME, CLINE_DIR, CLINE_DATA_DIR, and CONTINUE_GLOBAL_DIR. New profiles created later, custom client roots, remote hosts and containers need their own configuration. Project overrides remain authoritative where the client supports them; update never guesses between conflicting workspace keys. MCP usage instructions are delivered at connection time; whether the agent follows them also depends on the client and model.

When tools or memories are missing

Symptom	Check
Engram tools are absent after setup	Fully quit and reopen the AI client. Check that Node.js 20+ and npx are on the client's PATH.
Claude works, Codex does not	Each client has its own config. Run setup with --client codex; a project .mcp.json belongs to Claude.
A client sees another workspace	Run --doctor, then configure that client with the intended workspace key. --update preserves bindings.
Gemini will not load MCP	Inspect the client's folder-trust and MCP consent settings. Setup does not grant trust automatically.
A new project has no private memories	Describe the repo and task, complete real work, and preserve a durable learning. Use the same repo name across clients.

Never commit a config containing a key. Local clients need readable credentials; setup restricts generated config files to owner access on macOS/Linux.

Upgrade

Existing users can update the local MCP runtime and managed agent guidance without pasting their API key again:

npx -y engram-tools@latest --update

Engram reads and verifies the credentials already stored in MCP client configurations, refreshes each package entrypoint without changing its workspace binding, updates the managed instructions, and never prints a key. Restart the AI tool after the command completes. Use --client codex (or another supported selector) to update only one client. One setup installs user-scoped connections for use in other folders on the same machine. Existing project overrides keep their own workspace binding. Run --doctor from a folder where tools are missing; a remote host/container, another OS account, a new editor profile, or an untrusted folder can require its own client configuration or approval.

If the conversation was compacted, summarized, resumed, truncated, or the agent feels prior context is incomplete, call engram_rehydrate before continuing. It restores the session journal: where the agent left off, decisions, gotchas, open loops, and lessons since the last rehydrate. If the agent is mid-session and only needs focused task context, call engram_smarter.

Manual MCP config:

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

Clients that support remote MCP and OAuth can connect without a local API-key config:

https://api.engram.tools/mcp

The browser authorization flow creates or connects a free workspace and gives the client a restricted agent credential. It never exposes the owner API key or grants billing, invitation, or administration permissions.

Connection Diagnostics

Run npx -y engram-tools@latest --doctor (after the release containing this command), or npm run dev -- --doctor from a source checkout. Add --client codex to inspect only one client. This read-only check authenticates existing configurations, identifies their workspace/member binding, warns about invalid keys, missing Codex configuration, and different workspaces, and never prints credentials. A project's Claude .mcp.json does not configure Codex.

Use the intended workspace key with --setup --client <client> to repair a selected connection. --update preserves existing workspace bindings; it does not merge workspaces. Restart the client after changing its configuration.

Workspace memories are shared with teammates. Engram records the author for analytics and uses personal context only to break otherwise comparable retrieval-quality ties; stronger relevant teammate evidence still wins.

Data Protection

Private means workspace-scoped: authorized teammates can share knowledge. Explicitly public memories can be retrieved across workspaces. Hosted storage provides disk encryption and HTTPS; Engram still processes readable memory for retrieval and may send content to embedding/model providers. This is not end-to-end encryption. Do not store secrets or raw customer data as memories.

The server supports hashed API-key authentication with AES-256-GCM encryption for authorized key recovery. OAuth access/refresh tokens are stored as hashes. Operators must complete the staged key migration before claiming existing API-key rows are encrypted. See security and deployment requirements and the privacy page.

Core Tools

engram_start

Start a session in one call. This loads setup guidance, the Engram operating contract, and the most relevant memories. Use it at the beginning of a session, when entering a repo, or when task context changes. Use engram_rehydrate after compaction/resume. Skill guides are available on demand when the task needs a checklist.

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

engram_rehydrate

Restore working memory after context compaction, summary, resume, truncation, or agent confusion. This is the anti-context-compaction tool: it returns the latest checkpoint, decisions to preserve, gotchas to avoid, open loops, recent timeline, and the learning-path delta since the last rehydrate.

{
  "project": "HouseCompass",
  "repo": "housecompass.uk",
  "task": "continue the listing detail page",
  "reason": "conversation context was compacted",
  "depth": "standard"
}

engram_smarter

Load task-specific memories in one call. Use this after engram_start, when switching tasks, or when recovering focused context mid-session. Set include_skills: true only for checklist-heavy work such as review, security, migration, deployment, testing, performance, accessibility, or localization.

{
  "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

The published npm package is distributed under the MIT license. The hosted product source remains private.