{"id":50558007,"url":"https://github.com/athammad/memoire","last_synced_at":"2026-06-04T09:01:08.859Z","repository":{"id":358603602,"uuid":"1241442782","full_name":"athammad/memoire","owner":"athammad","description":"Persistent causal memory for AI coding assistants.","archived":false,"fork":false,"pushed_at":"2026-05-18T05:46:11.000Z","size":1909,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-18T07:37:16.159Z","etag":null,"topics":["causal-graphs","claude-code","gemini-ai","llm","memory-management","openai","token-usage"],"latest_commit_sha":null,"homepage":"https://athammad.github.io/memoire/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/athammad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-17T11:54:18.000Z","updated_at":"2026-05-18T06:16:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/athammad/memoire","commit_stats":null,"previous_names":["athammad/memoire"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/athammad/memoire","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/athammad%2Fmemoire","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/athammad%2Fmemoire/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/athammad%2Fmemoire/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/athammad%2Fmemoire/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/athammad","download_url":"https://codeload.github.com/athammad/memoire/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/athammad%2Fmemoire/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33897568,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["causal-graphs","claude-code","gemini-ai","llm","memory-management","openai","token-usage"],"created_at":"2026-06-04T09:01:08.304Z","updated_at":"2026-06-04T09:01:08.852Z","avatar_url":"https://github.com/athammad.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/logo.png\" alt=\"memoire\" width=\"180\"/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/memoire-ai\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/memoire-ai?color=blue\u0026label=PyPI\" alt=\"PyPI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/memoire-ai\"\u003e\u003cimg src=\"https://img.shields.io/pypi/pyversions/memoire-ai\" alt=\"Python\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/athammad/memoire/blob/master/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://athammad.github.io/memoire\"\u003e\u003cimg src=\"https://img.shields.io/badge/docs-online-blueviolet\" alt=\"Docs\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eYour project's causal memory. Builds itself. Never resets.\u003c/strong\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eUp to 87% fewer tokens per session \u0026nbsp;·\u0026nbsp; 0 file reads on session start \u0026nbsp;·\u0026nbsp; knows what breaks before you ask\u003c/em\u003e\n\u003c/p\u003e\n\n# memoire\n\nPersistent causal memory for AI coding assistants. Install it once — your assistant arrives at every session knowing not just what your project contains, but why things exist, what causes what, where changes will propagate, and what will break.\n\nWorks with **Claude Code**, **Cursor**, **Windsurf**, **OpenAI Codex CLI**, **Gemini CLI**, and **Ollama**.\n\n**Documentation:** https://athammad.github.io/memoire\n\n---\n\n## Install\n\n**Step 1 — Install SurrealDB** (the database memoire runs on):\n\n```bash\ncurl -sSf https://install.surrealdb.com | sh\n```\n\n**Step 2 — Install memoire:**\n\n```bash\n# Linux / Windows\npip install memoire-ai\n\n# macOS\nbrew tap athammad/memoire\nbrew install memoire-ai\n```\n\n**Step 3 — Set up in your project** (run once, from your project root):\n\n```bash\nmemoire init --provider claude   # or: cursor, windsurf, codex, gemini, ollama\nmemoire ingest                   # skip this if the project folder is empty\nmemoire install-service          # starts automatically on every login from now on\n```\n\nThat's it. Open a new session in your IDE — the assistant loads the full causal graph automatically. In Claude Code, you can also type `/memoire` to load it manually.\n\n\u003e **Projects with PDFs or images** (design docs, diagrams): run `pip install \"memoire-ai[pdf]\"` before `memoire ingest`.\n\n---\n\n## The problem\n\nEvery AI coding session starts from zero. The assistant re-reads the same files, re-establishes the same context, re-discovers the same architecture. But the deeper problem is worse: even after re-reading everything, it still has to reason about impact from scratch — \"if I change this function, what breaks?\" — by reading code rather than understanding intent and consequence.\n\n## The insight\n\nA project has layers of causality. A design document specifies a module. That module drives its dependents. Changes cascade downward. And within code, a function that writes shared state causes silent failures in anything that reads it — failures that don't show up until runtime.\n\nmemoire builds a **causal knowledge graph** that captures this structure. Not just what imports what, but what causes what to change, what will fail if something breaks, and why files exist at all.\n\nSee the [Theory \u0026 Design docs](https://athammad.github.io/memoire/theory/) for the full design rationale.\n\n## How it works\n\n```\nFile changes + AI assistant activity\n              ↓\n      Background Daemon\n   (watches files, captures hooks)\n              ↓\n          SurrealDB\n    (local graph + full-text search)\n              ↓\n         MCP Server\n              ↓\n  Assistant starts session with\n  full causal project model — instantly\n```\n\nThe graph evolves continuously. Every time a file is saved or the assistant edits it, edges are re-observed and their confidence scores increase. Causal patterns that persist across many sessions become highly confident. Transient patterns fade.\n\n## What you get\n\n| | Without memoire | With memoire |\n|---|---|---|\n| **Session start** | Re-reads 20,000–50,000 tokens of files | Loads 2,000–9,000 token causal graph |\n| **Impact analysis** | Opens files to reason about what breaks | Traverses graph edges — 0 file reads |\n| **Token cost (28-file project)** | ~58,000 tok / session | ~7,400 tok (structural) · ~23,000 tok (causal) |\n| **Token reduction** | baseline | **−87%** structural · **−60%** causal |\n| **File reads on session start** | N (one per file) | **0** |\n| **Works offline** | ✓ | ✓ (all data stored locally) |\n| **Supports PDFs \u0026 images** | — | ✓ (diagrams, design docs) |\n\nBreak-even: roughly 3 sessions on a project with 15+ files. See the [full benchmark](https://athammad.github.io/memoire/benchmark/) for methodology and results.\n\n## Relationship types\n\n| Relation | Direction | Type | Meaning |\n|---|---|---|---|\n| `SPECIFIES` | idea → code | causal | this doc defines the intent this file implements |\n| `IMPLEMENTS` | code → idea | causal | this file is the realization of that concept |\n| `DRIVES` | core → dependent | causal | changing this will force changes in that |\n| `DOCUMENTS` | doc → code | causal | this doc describes that file's behaviour |\n| `ASSERTS_ON` | test → module | causal, high-cost | this test will fail if that module changes |\n| `IMPORTS` | file → module | structural | static dependency, evidence for DRIVES |\n| `INHERITS` | class → class | structural | inheritance hierarchy |\n| `CONTAINS` | dir → child | structural | directory/file hierarchy |\n\nCausal edges are ranked above structural ones. High-cost edges (`ASSERTS_ON`, side-effect chains) surface first — breakage there has real-world consequences.\n\n## Provider support\n\n| Provider | Instructions file | MCP config | Activity hooks | Markdown LLM |\n|---|---|---|---|---|\n| Claude Code | `CLAUDE.md` | `.claude/settings.json` | ✓ PostToolUse / PreToolUse | `claude --print` CLI |\n| Cursor | `.cursor/rules/memoire.mdc` | `.cursor/mcp.json` | — | Anthropic API (`ANTHROPIC_API_KEY`) |\n| Windsurf | `.windsurfrules` | `~/.codeium/windsurf/mcp_config.json` | — | Anthropic API (`ANTHROPIC_API_KEY`) |\n| Codex CLI | `AGENTS.md` | `.codex/config.toml` | — | OpenAI API (`OPENAI_API_KEY`) |\n| Gemini CLI | `GEMINI.md` | `.gemini/settings.json` | — | Google API (`GEMINI_API_KEY`) |\n| Ollama | — | — | — | Local Ollama at port 11434 |\n\nFor providers without hooks (Cursor, Windsurf, Codex, Gemini, Ollama), the filesystem watcher tracks all file changes — activity-based temporal causality inference is unavailable but the full static analysis graph and LLM markdown extraction work identically.\n\n**API keys** — set the relevant environment variable before running `memoire ingest`:\n```bash\nexport ANTHROPIC_API_KEY=...   # cursor, windsurf\nexport OPENAI_API_KEY=...      # codex\nexport GEMINI_API_KEY=...      # gemini\n# ollama needs no key — runs at http://localhost:11434\n```\n\n## Commands\n\n| Command | Description |\n|---|---|\n| `memoire init` | Initialise memoire in the current project |\n| `memoire ingest` | Deep-read existing files — build full causal knowledge graph |\n| `memoire start` | Start the daemon (daemonizes — survives terminal close) |\n| `memoire stop` | Stop the running daemon |\n| `memoire install-service` | Install as a system service — auto-starts on every login (recommended) |\n| `memoire uninstall-service` | Remove the system service |\n| `memoire check` | Diagnose the memoire setup — SurrealDB, config, provider files, API key, graph state |\n| `memoire hook-event` | Called automatically by Claude Code hooks (internal) |\n| `memoire pre-read` | Called automatically before Claude reads a file (internal) |\n| `memoire mcp` | Start the MCP server (called automatically by Claude Code) |\n\n## Slash commands (Claude Code)\n\nAfter `memoire init`, four slash commands are installed in `.claude/commands/`:\n\n| Command | What it does |\n|---|---|\n| `/memoire` | Load the full causal graph — top relationships, project structure, recent events |\n| `/memoire-search \u003cquery\u003e` | Search the graph by keyword |\n| `/memoire-expand \u003cpath\u003e` | Show all relationships and metadata for a specific file |\n| `/memoire-recent` | Show recent file changes and inferred causal edges |\n\nThese call the memoire MCP tools without reading any source files.\n\n## What Claude can query\n\n**`get_context()`** — hierarchical project overview: directory/file tree, causal relationships ranked by centrality and confidence, recent events. Call at session start.\n\n**`expand(path)`** — full detail for a directory or file. Includes side-effect categories, mutable state attributes, all causal and structural relationships with their confidence scores.\n\n**`search(query)`** — full-text search across all stored knowledge.\n\n**`recent_events(limit)`** — what changed recently.\n\n## Causal scoring\n\nNodes are ranked by a composite score:\n\n- **BFS causal reachability × 2** — true downstream reach via graph traversal (not degree count). A node that causes changes in 10 files through a chain scores higher than one directly imported by 3. Root-cause nodes (specs, core modules) score highest.\n- **Causal in-degree** — how many causes point at this node.\n- **Side-effect cost** — files that do network calls, database writes, or file I/O score higher because their breakage has real-world consequences.\n- **Recency** — time-decay with a 7-day half-life.\n- **Access frequency** — how often Claude has read or edited this file.\n\nEdges are ranked by:\n- **Observations** — how many times this edge has been re-confirmed by reprocessing. Stable edges (seen 20+ times) rank above transient ones. This is how the graph learns.\n- **Causal bonus** — causal edges rank above structural ones.\n- **Cost bonus** — high-cost edges (`ASSERTS_ON`, side-effect chains) rank first.\n\n## Language support\n\n| Language | Side effects | Mutations | Imports | Inheritance | Test assertions |\n|---|---|---|---|---|---|\n| Python | ✓ | ✓ `self.attr` | ✓ | ✓ | ✓ `test_*.py`, `*_test.py`, `tests/` |\n| TypeScript / JS | ✓ | ✓ `this.attr` | ✓ | ✓ `extends` / `implements` | ✓ `.test.ts`, `.spec.ts`, `__tests__/` |\n| Go | ✓ | — | ✓ | — | ✓ `_test.go` |\n| Rust | ✓ | ✓ `self.field` | ✓ `use` | ✓ `impl Trait for` | ✓ `_test.rs`, `tests/` |\n| Java | ✓ | ✓ `this.field` | ✓ `import` | ✓ `extends` / `implements` | ✓ `*Test.java`, `src/test/` |\n| Ruby | ✓ | ✓ `@attr` | ✓ `require` | ✓ `class \u003c Parent` | ✓ `_spec.rb`, `_test.rb`, `spec/` |\n| C / C++ | ✓ | — | ✓ `#include` | ✓ `: public` | ✓ `test_*.c`, `*_test.cpp` |\n| Markdown / RST | — | — | — | — | — |\n\nAll languages feed into the same causal graph with the same promotion rules: high-fan-in IMPORTS → DRIVES, test imports → ASSERTS_ON, mutation sources → DRIVES to importers.\n\nMarkdown files use LLM extraction (provider-configurable) to produce intentional causal edges: SPECIFIES, IMPLEMENTS, DRIVES, DOCUMENTS.\n\n## What gets stored\n\n**From Python files:**\n- Import dependencies (IMPORTS) and class inheritance (INHERITS)\n- Side-effect categories detected by pattern: `network`, `file_io`, `subprocess`, `database`, `cache`\n- Mutable state attributes (`self.attr = ...`) — used to infer DRIVES edges to importers\n- Test files (matching `test_*.py`, `*_test.py`, or in `tests/`) emit `ASSERTS_ON` edges for everything they import\n\n**From TypeScript / JS files:**\n- Import dependencies (IMPORTS), class inheritance (INHERITS), interface implementation (IMPLEMENTS)\n- Same five side-effect categories detected by pattern\n- Mutable state attributes (`this.attr = ...`) — same mutation-driven DRIVES inference\n- Test files (`.test.ts`, `.spec.ts`, `__tests__/`) emit `ASSERTS_ON` edges for everything they import\n\n**From Go files:**\n- Import dependencies (IMPORTS) from single imports and import blocks\n- Side-effect categories: `network`, `file_io`, `subprocess`, `database`\n- Test files (`_test.go`) emit `ASSERTS_ON` edges for everything they import\n\n**From markdown files:**\n- Full content stored and indexed for search\n- Claude extracts causal relationships: SPECIFIES, IMPLEMENTS, DRIVES, DOCUMENTS — with a rationale for each\n\n**From Claude Code activity:**\n- Sequential file edits within 5 minutes generate inferred DRIVES edges, reinforced on repetition\n- Bash commands (git, pip, npm, pytest, etc.) stored as episodic events\n- Every file read or edit bumps `access_count` and `observations` on related edges\n\n**Structural promotions (run after every ingest and every 10 file changes):**\n- High-fan-in IMPORTS → promoted to DRIVES (modules imported by 3+ files are causal roots)\n- Test IMPORTS → promoted to ASSERTS_ON (high-cost)\n- Mutation sources with importers → promoted to DRIVES (mutation-driven dependency)\n\n**Graph integrity (Phase 3):**\n- Every edge carries `extracted_from` — the file that produced it via static analysis\n- When a file is reprocessed, edges no longer present in it are pruned (deleted import → edge removed)\n- When a file is deleted from disk, its entity and all edges touching it are removed instantly\n- Cycle detection runs after every ingest and promotion batch — causal edges must form a DAG; violations are logged as warnings\n\n## Storage\n\nAll data is stored locally in SurrealDB — nothing leaves your machine. Each project has an isolated namespace.\n\n## Project structure\n\n```\n.memory/\n  config.json        # project namespace\n.claude/\n  settings.json      # hooks + MCP server (managed by memoire)\nCLAUDE.md            # instructions for Claude (managed by memoire)\n```\n\n## Testing\n\nThe extraction and scoring logic is covered by a unit test suite:\n\n```bash\npip install -e \".[dev]\"\npytest tests/\n```\n\n135 tests covering: test-path detection across all 7 languages, side-effect detection, state mutation extraction, static extractors for Python/TypeScript/JS/Go/Rust/Java/Ruby/C/C++, BFS causal reachability, causal scoring, cycle detection, and LLM response parsing.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fathammad%2Fmemoire","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fathammad%2Fmemoire","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fathammad%2Fmemoire/lists"}