Engram

Persistent memory for AI agents, backed by SQLite + FTS5.

Measured impact: across five realistic tool-output scenarios (587 KB of raw text), Engram persists ~8% on disk and surfaces just ~0.08% per recall call — a ~1250× reduction at the recall path. Search returns in <1 ms; intake in ~2 ms. See BENCHMARK.md for the full table and python scripts/benchmark.py to reproduce.

Install

pip install engram-ms

Optional extras:

pip install "engram-ms[llm]"
pip install "engram-ms[semantic]"
pip install "engram-ms[mcp]"
pip install "engram-ms[full]"

memorytrace is the legacy distribution name on PyPI and is no longer updated in lockstep with engram-ms. New installs should use engram-ms.

Simple CLI

The default CLI is engram. python -m engram is equivalent.

engram init
engram save "Minseong Jeong is the CTO of Galaxy Corp"
engram find "CTO"
engram who "Minseong Jeong"
engram remember "Minseong Jeong" "Interested in AI and robotics"
engram status

Advanced CLI

Use engram-advanced when you need structured options, JSON output, or a custom DB path.

engram-advanced --db ~/.engram/memory.db search "Galaxy Corp" --max-results 5
engram-advanced --json health

Python SDK

from engram.integrations.sdk import EngramSDK

with EngramSDK() as sdk:
    sdk.start_session("assistant")
    sdk.store("Minseong Jeong is the CTO of Galaxy Corp")
    sdk.add_fact("Minseong Jeong", "Interested in AI and robotics")
    result = sdk.search("Galaxy")
    print(result.to_agent_context())

Source Checkout Compatibility

A repo-local python mem ... wrapper is kept for backward compatibility in source checkouts. It forwards to the same simple CLI as engram, but it is not installed as a packaged console script.

Related packages

This project publishes as engram-ms. memorytrace remains only as the legacy distribution name:

Docs

• Quickstart
• CLI commands
• Setup guide

Workspace Skill

The static project wiki helper is source-checkout tooling, not part of the packaged runtime. From a repository checkout, generate the site with:

python tools/run_engram_tree.py

Install the skill for Claude Code and Codex with:

python tools/install_engram_tree_skill.py --dry-run
python tools/install_engram_tree_skill.py --create-missing

Bridge to Claude Code / Codex CLI (engram-ctx)

After pip install "engram-ms[mcp]", register engram-ctx as a memory bridge in your CLI of choice:

# Claude Code
engram-ctx install claude-code

# Codex CLI
engram-ctx install codex

Both installers are idempotent. They register:

• MCP server engram exposing engram_ctx_index, engram_ctx_fetch_and_index, engram_ctx_search, engram_ctx_get, engram_ctx_recall_digest, engram_ctx_stats, engram_ctx_doctor, engram_ctx_purge (in addition to the existing memory_* tools).
• Lifecycle hooks: Claude Code registers SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, PreCompact, and Stop; Codex registers SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, and Stop. Large tool outputs (>500 chars) are auto-indexed into tool_observations (PII-masked, head/tail truncated). Recall via engram_ctx_search.
• Skill engram-context with caveman-style output compression and routing rules.

For non-hook MCP clients (Cursor, Copilot CLI, OpenCode), use engram.integrations.mcp_middleware.EngramContextMiddleware directly.