Metadata-Version: 2.4
Name: engram-ms
Version: 1.8.1
Summary: Engram — AI agent memory system with SQLite+FTS5, MCP integration, and quality gates. Canonical distribution (formerly published as 'memorytrace').
Project-URL: Homepage, https://github.com/aop60003/default
Project-URL: Documentation, https://github.com/aop60003/default/blob/main/docs/README.md
Project-URL: Changelog, https://github.com/aop60003/default/blob/main/CHANGELOG.md
Project-URL: Source, https://github.com/aop60003/default
Project-URL: Releases, https://github.com/aop60003/default/releases
Project-URL: Issues, https://github.com/aop60003/default/issues
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,fts5,llm,mcp,memory,sqlite
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: tomlkit>=0.13.0
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: hatchling>=1.25.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: packaging>=24.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Requires-Dist: twine>=6.0.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: anthropic>=0.40.0; extra == 'full'
Requires-Dist: mcp>=1.0.0; extra == 'full'
Requires-Dist: numpy>=1.24.0; extra == 'full'
Requires-Dist: openai>=1.50.0; extra == 'full'
Provides-Extra: llm
Requires-Dist: anthropic>=0.40.0; extra == 'llm'
Requires-Dist: openai>=1.50.0; extra == 'llm'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Provides-Extra: semantic
Requires-Dist: numpy>=1.24.0; extra == 'semantic'
Requires-Dist: openai>=1.50.0; extra == 'semantic'
Description-Content-Type: text/markdown

# 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](https://github.com/aop60003/default/blob/main/BENCHMARK.md)
for the full table and `python scripts/benchmark.py` to reproduce.

## Install

```bash
pip install engram-ms
```

Optional extras:

```bash
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.

```bash
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.

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

## Python SDK

```python
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:

| Package | Status | Purpose |
|---|---|---|
| [`engram-ms`](https://pypi.org/project/engram-ms/) | canonical package | Current distribution and preferred install path |
| [`memorytrace`](https://pypi.org/project/memorytrace/) | legacy package | Historical distribution name; may lag current `engram-ms` releases |

## Docs

- [Quickstart](https://github.com/aop60003/default/blob/main/docs/04-usage-guide/01-quickstart.md)
- [CLI commands](https://github.com/aop60003/default/blob/main/docs/01-project-analysis/05-cli-commands.md)
- [Setup guide](https://github.com/aop60003/default/blob/main/docs/01-project-analysis/09-setup-guide.md)

## 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:

```bash
python tools/run_engram_tree.py
```

Install the skill for Claude Code and Codex with:

```bash
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:

```bash
# 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.
