engram-team 0.1.0

Engram gives your team's agents a shared, persistent memory that survives across sessions and detects when two agents develop contradictory beliefs about the same codebase.

You bring your own database. Engram never owns your data.

Individual agent memory is solved. Engram solves what happens when multiple agents need to agree on what's true.

How it works

Every agent on your team connects to the same knowledge base. When one agent discovers something — a hidden side effect, a failed approach, an undocumented constraint — it commits that fact. Every other agent on the team can query it instantly.

When two agents develop incompatible beliefs about the same system, Engram detects the contradiction and surfaces it for review. No silent divergence.

Install

pip install engram-team
engram install

engram install auto-detects your MCP client (Claude Code, Cursor, Windsurf) and adds the config. Restart your editor and open a new chat — your agent handles everything else.

What happens after install

Your agent calls engram_status() on its first tool use and walks you through setup. No docs to read. No JSON to edit.

Setting up a new workspace (team founder):

Agent: "Do you have a Team ID to join an existing workspace,
        or are you setting up a new one?"

You:   "New"

Agent: "Add your database connection string to your environment:

          export ENGRAM_DB_URL='postgres://...'

        You can get a free PostgreSQL database at neon.tech,
        supabase.com, or railway.app. Tell me when it's set."

[You set ENGRAM_DB_URL]

Agent: "Your team workspace is ready.

        Share with teammates:
          Invite Key: ek_live_abc123...

        That's all they need.
        Should commits show who made them, or stay anonymous?"

Joining a workspace (teammate):

Agent: "Do you have an Invite Key to join an existing workspace,
        or are you setting up a new one?"

You:   "Join"

Agent: "What's your Invite Key?"
You:   "ek_live_abc123..."

Agent: "You're in. I'll query team memory before starting any task."

Teammates only need one thing — the Invite Key. The workspace ID and database connection are encrypted inside it and extracted automatically. No one except the workspace founder ever sees or handles a database URL.

Every session after that: the agent connects silently, queries before every task, commits after every discovery. Engram is invisible infrastructure.

You own your data

Engram connects to a PostgreSQL database you provide. Your facts, conflicts, and agent history live in your database — not ours.

• Use Neon, Supabase, Railway, or any PostgreSQL instance
• Self-host if you want zero third-party involvement
• The database URL is never stored by Engram — only in ~/.engram/workspace.json on your machine (mode 600)
• The invite key carries the database URL encrypted inside it — teammates never see it in plaintext

Privacy settings (asked once during setup, enforced server-side):

• Anonymous mode — strip engineer names from all commits
• Anonymous agents — randomize agent IDs each session

Tools

Engram exposes seven MCP tools. The first three handle setup; the last four are the knowledge layer.

Tool	Purpose
engram_status	Check setup state. Returns next_prompt — the agent says it to you.
engram_init	Create a new workspace (founder). Generates Team ID + Invite Key.
engram_join	Join a workspace with just an Invite Key. Extracts workspace ID + db URL automatically.
engram_query	Pull what your team's agents collectively know about a topic.
engram_commit	Persist a verified discovery — fact, constraint, decision, failed approach.
engram_conflicts	Surface pairs of facts that semantically contradict each other.
engram_resolve	Settle a disagreement: pick a winner, merge both sides, or dismiss.

Conflict detection

Contradiction detection runs asynchronously in the background using a tiered pipeline:

Tier	Method	Catches
0	Deterministic entity matching	"rate limit is 1000" vs "rate limit is 2000"
1	NLI cross-encoder (local, CPU)	Semantic contradictions in natural language
2	Numeric + temporal rules	Different values for the same named entity
2b	Cross-scope entity detection	Contradictions spanning different scopes
3	LLM escalation (rare, optional)	Ambiguous cases needing domain understanding

Commits return instantly. Detection completes in the background. The write lock is held for ~1ms.

Architecture

┌──────────────────────────────────────────┐
│            I/O Layer (MCP)               │  ← agents connect here (stdio)
│  engram_status / engram_init /           │
│  engram_join / engram_commit /           │
│  engram_query / engram_conflicts /       │
│  engram_resolve                          │
├──────────────────────────────────────────┤
│          Detection Layer                 │  ← runs asynchronously
│  Tier 0: entity exact-match             │
│  Tier 1: NLI cross-encoder (local)      │
│  Tier 2: numeric / temporal rules       │
│  Tier 2b: cross-scope entity detection  │
│  Tier 3: LLM escalation (rare)          │
├──────────────────────────────────────────┤
│          Storage Layer                   │
│  Local:  SQLite  (~/.engram/)            │
│  Team:   PostgreSQL (your ENGRAM_DB_URL) │
└──────────────────────────────────────────┘

Team sharing works through the shared database — no HTTP server, no port forwarding, no firewall rules. Every team member runs their own local Engram process connected to the same PostgreSQL instance.

Solo use (no team)

No database needed. Engram defaults to local SQLite:

{
  "mcpServers": {
    "engram": {
      "command": "uvx",
      "args": ["engram-team@latest"]
    }
  }
}

Facts persist in ~/.engram/knowledge.db. Add ENGRAM_DB_URL later to upgrade to team mode — the agent handles migration automatically.

Research foundation

Engram is grounded in peer-reviewed research on multi-agent memory systems:

• Yu et al. (2026) — frames multi-agent memory as a computer architecture problem; names consistency as the most pressing open challenge
• Xu et al. (2025) — A-Mem's Zettelkasten note structure informs fact enrichment
• Rasmussen et al. (2025) — Graphiti's bitemporal modeling directly inspired the temporal validity design
• Hu et al. (2026) — survey confirming shared multi-agent memory as an open frontier

Full literature review: LITERATURE.md · Implementation details: docs/IMPLEMENTATION.md

Contributing

PRs welcome. See CONTRIBUTING.md for guidelines.

License

Apache 2.0

---