Cogram
Intent-aware memory for LLM agent.Why every connection exists?, not just that it does.
Install / Use
npx skills add srk0102/cogramInstalls into whichever agent you are using.
README
Note
Cogram is a fork of Graphiti by Zep AI Research, with an intent-capture layer baked in directly. Where graphiti gives you a temporal context graph, cogram extends every fact with why it exists, what goal it serves, and how the user thinks — a pre-synthesized model that any LLM agent can consume across surfaces.
⭐ Help us reach more developers and grow the community. Star this repo!
Tip
Cogram ships an MCP server out of the box. Connect Claude Desktop, Cursor, Windsurf, or any MCP client to give your agent persistent intent-aware memory.
Cogram is a framework for building and querying intent graphs — temporal context graphs that capture not just what facts exist, but why the user holds them and what underlying goal each fact serves. Built on a fork of Graphiti, cogram inherits temporal validity windows, multi-database driver support, and hybrid retrieval, then adds:
- Per-edge intent annotation (
why_connected,director_vision,cognitive_pattern) - Per-entity narration (
vllm_narrativewith stance and open questions) - DirectorProfile distillation — a model of how the user thinks
- Engram cache (Postgres-backed) — repeat LLM calls cost zero
- Redis active subgraph (hot tier, <1ms reads)
- Knot synthesis with local Gemma — pre-compressed hub narratives at $0 marginal cost
- MCP server with 14 tools for Claude Desktop / Cursor / any agent — see docs/agent_playbook.md
Use Cogram to:
- Build memory that survives across surfaces — Claude in your terminal, Claude in your browser, Cursor, custom GPT-4 agents — all reasoning the same way about your decisions because they share the same
why_connectedanddirector_visionfor every fact. - Forecloses wrong agent routes by recording the principle behind a decision, not just the rule.
- Query across time, meaning, relationships, and intent with hybrid retrieval (semantic + keyword + graph traversal + profile-aware Cypher).
- Pre-synthesize hub-node narratives once with local Gemma, reuse forever — agent cost approaches zero on warm reads.
What is an Intent Graph?
An intent graph is a temporal context graph (à la Graphiti) plus an intent layer. Each edge carries not just a fact and a validity window, but the user's reasoning about that fact:
| Component | What it stores |
|---|---|
| Entities (nodes) | People, products, policies, concepts — with summaries that evolve over time |
| Facts / Relationships (edges) | Triplets (Entity → Relationship → Entity) with temporal validity windows |
| Episodes (provenance) | Raw data as ingested — every derived fact traces back here |
| Custom Types (ontology) | Developer-defined entity and edge types via Pydantic models |
| ★ intent_meta (per edge) | why_connected (the reason this link exists), director_vision (the larger goal it serves), cognitive_pattern (the thinking style it reveals) |
| ★ vllm_narrative (per hub entity) | Second-person narrative + user's stance + open questions + cognitive_pattern_label |
| ★ :DirectorProfile (top of graph) | Distilled summary of how the user thinks — recurring visions, working-style summary, ranked cognitive patterns |
| ★ :CognitivePattern (aggregated) | Reusable thinking labels (e.g. legal risk mitigation, data-driven validation) — reinforced by edges, decayed by inactivity |
| ★ :knot_narrative (per hub) | Pre-synthesized prose paragraph from local Gemma — drop directly into LLM context |
★ = additions on top of Graphiti.
Cogram and Graphiti
Cogram is a fork of Graphiti, the open-source temporal context graph engine by Zep AI Research. The forked graphiti code lives directly inside the cogram/ package — no separate graphiti-core install. We track Graphiti's design and extend it with the intent layer.
Cogram vs Graphiti
| Aspect | Graphiti | Cogram |
|---|---|---|
| What it is | OSS temporal context graph engine | OSS intent graph engine (fork of graphiti) |
| Per-edge why_connected / director_vision / cognitive_pattern | – | ✅ |
| Per-entity narration with stance + open questions | – | ✅ |
| DirectorProfile + CognitivePattern aggregation | – | ✅ |
| Pre-synthesized hub narratives (knots) | – | ✅ Gemma local + GPT fallback |
| Engram-style decision cache | – | ✅ Postgres-backed |
| Redis active subgraph (hot tier) | – | ✅ |
| MCP server (turnkey) | partial (separate mcp_server dir) | ✅ baked into core, 14 tools |
| Multi-DB drivers (Neo4j, FalkorDB, Kuzu, Neptune) | ✅ | ✅ inherited |
| Bi-temporal model with validity windows | ✅ | ✅ inherited |
| Hybrid BM25 + vector + graph retrieval | ✅ | ✅ inherited + profile-aware Cypher traversal |
| LLM providers (OpenAI / Anthropic / Gemini / Groq) | ✅ | ✅ inherited |
| Drift / contradiction handling | LLM-driven judgments | ✅ Cosine drift gate + classifier with 5× weight on contradictions |
| Confidence decay | basic | ✅ 30-day exponential half-life |
| PostHog telemetry | enabled by default | disabled by default — no analytics ping out |
When to choose which
- Choose Graphiti if you want the lean temporal context graph engine and you're comfortable building the intent / agent / cache layers yourself.
- Choose Cogram if you want the same temporal substrate plus an intent layer that makes multi-surface agents reason consistently, plus a turnkey MCP server, plus a cache architecture that approaches zero cost on warm reads.
Why Cogram?
Most LLM memory products store what the user said. When a different agent (Claude in your terminal vs. Claude in your browser vs. a custom GPT) reads the same memory, each invents its own reasoning around bare facts. The agents drift apart and recommend conflicting actions.
Cogram solves this by storing the why alongside the what. Every fact carries the user's reasoning, the larger goal it serves, and the thinking pattern it reveals. Any agent reading cogram converges on the same interpretation — they're forced into the same lane because they all see the same why_connected and director_vision.
This is canonical multi-surface context — not just memory.
Concrete example: graphiti vs cogram on the same scenario
A user tells Claude: "I rejected server-side LinkedIn scraping because of legal issues. We use a Chrome extension during the end-user's logged-in session instead."
Graphiti alone stores:
(User) -[REJECTED]-> (server-side LinkedIn scraping)
fact: "User rejected server-side LinkedIn scraping"
A future agent reading this thinks: "Maybe the user will accept it now if I phrase it differently." → wrong route.
Cogram stores the same edge with intent_meta:
{
"fact": "User rejected server-side LinkedIn scraping",
"intent_meta": {
"why_connected": "Server-side scraping conflicts with LinkedIn ToS, creating legal risk",
"director_vision": "Build a legally compliant AI recruitment platform",
"cognitive_pattern": "legal risk mitigation"
}
}
A future agent in any interface reasons: "User's vision is legal compliance. So scraping Indeed via residential proxies would be rejected by the same logic, even though we never specifically discussed Indeed." → right route, every time, across every surface.
Cogram vs other memory products
| Aspect | mem0 | Zep | Letta | Cogram | |---|---|---|---|---| | Stores facts | ✅ | ✅ | ✅ | ✅ | | Temporal validity windows | – | ✅ | – | ✅ inherited from graphiti | | Per-edge intent (why+vision+pattern) | ❌ | ❌ | ❌ | ✅ | | Per-entity narration with stance | ❌ | ❌ | ❌ | ✅ | | Distilled "how the user thinks" profile | ❌ | partial | – | ✅ | | Pre-synthesized agent-ready paragraphs | ❌ | ❌ | ❌ | ✅ Gemma local | | Cost on warm reads | scales with LLM | scales with LLM | scales | near zero (Engram cache) | | MCP server | partial | – | – | ✅ 14 tools | | Self-hostable / OSS | ✅ | hosted SaaS only | ✅ | ✅ Apache 2.0 |
Requirements
- Docker (Compose v2) — for the simplest install path
- OpenAI API key — for entity extraction, intent annotation, narration, profile distillation
- (Optional) Ollama with
gemma3n:e4bmodel pulled — for free local knot synthesis (falls back to gpt-4o-mini if not available)
For Python development:
- Python 3.10 or higher
- One of: Neo4j 5.26 / FalkorDB 1.1.2 / Kuzu 0.11.2 / Amazon Neptune
Important
Cogram works best with LLM services that support Structured Output (OpenAI, Gemini). Other services may produce inconsistent intent_meta and narrative schemas, particularly with smaller models.
Tip
The simpl
Related Skills
codebase-memory-mcp
38.2kHigh-performance code intelligence MCP server. Indexes codebases into a persistent knowledge graph — average repo in milliseconds. 158 languages, sub-ms queries, 99% fewer tokens. Single static binary, zero dependencies.
codebase-memory-mcp
38.2kHigh-performance code intelligence MCP server. Indexes codebases into a persistent knowledge graph — average repo in milliseconds. 158 languages, sub-ms queries, 99% fewer tokens. Single static binary, zero dependencies.
codebase-memory-mcp
38.2kHigh-performance code intelligence MCP server. Indexes codebases into a persistent knowledge graph — average repo in milliseconds. 158 languages, sub-ms queries, 99% fewer tokens. Single static binary, zero dependencies.
tabularis
4.0kOpen-source desktop SQL workspace for PostgreSQL, MySQL/MariaDB, SQLite and 15+ more databases like DuckDB, ClickHouse, Redis and Firestore. Built-in MCP server for Claude, Cursor and Devin, SQL notebooks and visual EXPLAIN.
