Skip to content
Back to search

atlas

Open-source local-first cognitive memory. AGM-compliant belief revision (49/49 postulates). When a fact changes, downstream beliefs are automatically re-evaluated, not just flagged.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/richschefren--atlas/badge.svg)](/listings/richschefren--atlas)

HTML

<a href="/listings/richschefren--atlas"><img src="/api/listings/richschefren--atlas/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> Three good install paths depending on why you want Atlas — researcher / dev, Obsidian power-user, or agent-runtime integration. Each one is self-contained and documented in [`docs/INSTALL_MODES.md`](docs/INSTALL_MODES.md). The block below is the universal version that works for all three.

# 1. Clone
git clone https://github.com/RichSchefren/atlas && cd atlas

# 2a. Prove portable Hermes/OpenClaw storage + retrieval (no Docker)
python -m venv .venv && source .venv/bin/activate
pip install -e .
PYTHONPATH=. python scripts/demo_runtime_adapters.py

# 2b. Native Hermes: install its managed cognitive service (no Docker)
bash integrations/hermes-atlas/install.sh

# 2c. Or install the native OpenClaw / GBrain cognitive package
bash integrations/openclaw-atlas/install.sh
bash integrations/gbrain-atlas/install.sh

# 2d. Optional broader property-graph/MCP/adjudication tier
docker compose up -d                               # bolt://localhost:7687

# 3. Install — base is deterministic + $0/month; opt in to extras as you need them
pip install -e .              # core: AGM + Ripple + ledger + adapters + ingest
# pip install -e ".[llm]"        # add Anthropic SDK for LLM-driven extraction
# pip install -e ".[embeddings]" # add sentence-transformers (~2GB; rarely needed — vault-search is the default retrieval path)
# pip install -e ".[benchmarks]" # add Mem0 / Letta clients for the BMB matrix
# pip install -e ".[full]"       # everything above
# pip install -e ".[dev]"        # contributor tooling (includes anthropic for tests)

# 4. Verify with the test suite (532 tests in this snapshot)
PYTHONPATH=. pytest tests/ -v

# 5. Reproduce AGM compliance (49/49 scenarios, ~30s)
PYTHONPATH=. pytest tests/integration/test_agm_compliance.py -v

# 6. First real ingest from your own Obsidian vault
ATLAS_VAULT_ROOT=~/Documents/Obsidian PYTHONPATH=. python scripts/first_real_run.py

# 6b. Multiple vaults (colon-separated, like PATH) — e.g. a shared business
#     vault plus a personal vault feeding one belief graph
ATLAS_VAULT_ROOTS=~/Vaults/business:~/Vaults/personal PYTHONPATH=. python scripts/first_real_run.py

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 556 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Atlas
  2. > **Open-source local-first cognitive memory — alpha.** Implements AGM-compliant belief revision on a property graph. Adds a propagation engine — Ripple — that recomputes downstream beliefs when an upstream fact changes. Runs entirely on your laptop.
  3. [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
  4. [![Tests](https://github.com/RichSchefren/atlas/actions/workflows/test.yml/badge.svg)](https://github.com/RichSchefren/atlas/actions/workflows/test.yml)
  5. [![AGM Compliance](https://img.shields.io/badge/AGM-49%2F49%20at%20100%25-brightgreen.svg)](docs/AGM_COMPLIANCE.md)
  6. [![Status: alpha](https://img.shields.io/badge/Status-alpha-orange.svg)]()
  7. [![Atlas in 90 seconds — a fact changes, Ripple re-evaluates every belief that depended on it](site/atlas-hero.gif)](https://livememory.pages.dev)
  8. *↑ 3× preview — [watch the narrated 90-second version with sound](https://livememory.pages.dev). The story behind it is [on X](https://x.com/richschefren/status/2065318023007814017) — reply with the stale belief that bit you.*
  9. > **Alpha:** the propagation loop works end-to-end (`./demo.sh` proves it in 12 seconds). Ingestion and entity resolution on truly unstructured text are still maturing — see `atlas_core/ingestion/` for the prompts we're iterating on.
  10. ---
  11. ## See it work in 12 seconds
  12. ```bash
  13. git clone https://github.com/RichSchefren/atlas && cd atlas
  14. docker compose up -d
  15. python3 -m venv .venv && source .venv/bin/activate
  16. pip install -e ".[dev]"
  17. ./demo.sh
  18. ```
  19. The `./demo.sh` command runs the entire loop end-to-end, visibly:
  20. 1. Plants a tiny graph (3 nodes, 2 `Depends_On` edges)
  21. 2. Changes a fact (Origins coffee price: $89 → $129)
  22. 3. Calls `RippleEngine.propagate()` — the real orchestrator
  23. 4. Shows reassessment proposals, contradictions, and routing decisions
  24. 5. Resolves one through `adjudication.resolve()` (real AGM revise)
  25. 6. Verifies the SHA-256 hash chain
  26. Every line is real Neo4j + real ledger. No mocks. ~6s on subsequent runs. **This is the front door — if it doesn't impress, nothing else will.**
  27. ### What you should see
  28. The final stages of `./demo.sh` should look like this — if they don't, file an issue:
  29. ```text
  30. ▶ Stage 4 / 7 — RippleEngine.propagate()
  31. ✓ cascade complete
  32. impacted nodes: 2
  33. contradictions: 0
  34. routing — auto: 1, strategic: 1, core: 0
  35. ▶ Stage 5 / 7 — Reassessment proposals
  36. 1. kref://AtlasDemo/Beliefs/origins_accessible.belief
  37. 0.88 → 0.75 (-0.13)
  38. 2. kref://AtlasDemo/Decisions/marketing_to_newcomers.decision
  39. 0.80 → 0.66 (-0.14)
  40. ▶ Stage 6 / 7 — Resolve one through adjudication
  41. ✓ resolved with decision='accept'
  42. ▶ Stage 7 / 7 — Verify SHA-256 ledger chain
  43. ✓ chain intact at sequence 1
  44. LOOP CLOSED.
  45. ```
  46. `last_verified_sequence = 1` looks small because the demo plants exactly one promotion-eligible fact and verifies the chain holds with one entry — every later run extends the chain and the number grows. The point is the chain *intact*, not the count.
  47. The installed Python package also exposes an `atlas` command:
  48. ```bash
  49. atlas --help
  50. atlas status
  51. atlas queue --json
  52. atlas search "current pricing belief"
  53. atlas ingest
  54. ```
  55. `atlas demo` delegates to the complete repository `demo.sh`, so that one
  56. command requires a source checkout. The operational commands work from an
  57. installed package.
  58. ### What Atlas is not
  59. To save you time:
  60. - **Not a chatbot memory UI.** Atlas is a graph + an engine. The "UI" is whatever your agent runtime (Claude Code, Hermes, OpenClaw, your own MCP client) exposes. The Obsidian adjudication queue is markdown, not a chat interface.
  61. - **Not just vector search.** There's an embedding-aware retrieval layer, but Atlas's primary index is the typed `Depends_On` graph. Vector-only systems can retrieve old context; Atlas reassesses what depended on it. ([Worked example with stale-belief failure mode →](docs/WHY_VECTOR_IS_NOT_ENOUGH.md))
  62. - **Not yet a Letta replacement.** Atlas does not run agent loops. It plugs into agent runtimes as a memory backend. If you want an agent stack with memory built in, Letta or Hermes is the right answer; Atlas slots underneath.
  63. - **Not yet automatic free-text understanding at scale.** The ingestion pipeline works on real Limitless / Fireflies / Claude transcripts, but extraction quality on truly unstructured text is uneven and improving — see `atlas_core/ingestion/extractors/` for the prompt set we're iterating on.
  64. ### Hermes, OpenClaw, and GBrain: real independent packages
  65. The adapter cores now perform real local `store`, `search` / `recall`, `get`,
  66. `list`, and `forget` operations against Atlas's SQLite trust store. This path
  67. does **not** require Neo4j, Docker, an embedding model, or an API key:
  68. ```bash
  69. PYTHONPATH=. python scripts/demo_runtime_adapters.py
  70. ```
  71. CI runs that proof with the Neo4j endpoint deliberately pointed at a dead port.
  72. Atlas also ships native packages for current Hermes Agent, OpenClaw, and GBrain:
  73. [`integrations/hermes-atlas/`](integrations/hermes-atlas/) implements Hermes's
  74. `MemoryProvider` lifecycle, and
  75. [`integrations/openclaw-atlas/`](integrations/openclaw-atlas/) is a TypeScript
  76. memory-capability plugin. [`integrations/gbrain-atlas/`](integrations/gbrain-atlas/)
  77. is a package-only MCP bridge that keeps GBrain pages authoritative while Atlas
  78. adds page-linked cognition. All three are tested against pinned upstream
  79. contracts and require no Neo4j or Docker for retrieval or the bounded
  80. AGM/Ripple service.
  81. Hermes, OpenClaw, and GBrain now share one proven cognitive boundary: their native packages
  82. manage a profile-scoped, authenticated localhost service that owns AGM
  83. revision, dependency traversal, and persisted Ripple proposals. Cognitive
  84. records participate in recall, search, list, get, forget, audit, and restart.
  85. The service uses SQLite for persistence but keeps cognitive semantics in one
  86. Python owner, not in host-specific adapters or SQL. Hermes manages one service
  87. per profile, OpenClaw manages one per agent/session scope, and the GBrain
  88. bridge maps brain + source + slug to a stable Atlas identity. Its black-box suite covers
  89. 49 AGM scenario IDs plus the canonical A-to-B cascade, and its 10k/20k
  90. performance contract is enforced in CI.
  91. OpenClaw's protected host proof executes all seven tools, including dependency
  92. declaration and a revision that must emit a nonempty Ripple proposal set.
  93. GBrain's protected host proof installs the package-only tarball and drives the
  94. real pinned `gbrain serve` MCP lifecycle. The exact capability split and installation paths are in
  95. [`docs/RUNTIME_ADAPTERS.md`](docs/RUNTIME_ADAPTERS.md).
  96. ### Who Atlas is for, today
  97. The strongest early users are:
  98. - **Agent / tool builders** who need a memory backend with belief-revision semantics (MCP/HTTP surfaces plus native Hermes/OpenClaw/GBrain packages ship today).
  99. - **Power users with Obsidian / transcripts / vaults** who want their meetings + screen + chat captures cross-checked for emergent contradictions.
  100. - **Local-first AI builders** who can't or won't ship user data to a cloud memory service.
  101. - **Researchers** working on belief revision, AGM compliance, or non-monotonic reasoning who want a reproducible, instrumented baseline.
  102. Three concrete shapes the loop solves:
  103. 1. **Pricing change invalidates positioning.** A program's price changes from $89 to $129. Every "value claim" belief that quoted $89 gets a reassessment proposal — you don't discover the gap mid-call.
  104. 2. **Partner / person status change.** A team member changes role or leaves. Every Decision and Commitment that depended on their owning a deliverable surfaces in the adjudication queue with a confidence drop, not just a "stale" warning.
  105. 3. **Deadline slips.** A milestone moves three weeks. Every Project belief that downstream-depended on the old date (resourcing assumptions, risk score, dependent commitments) gets re-evaluated — and the contradictions that emerge route to Obsidian for you to resolve.
  106. ### Look at the graph yourself
  107. After running `./demo.sh`, open `http://localhost:7474` (default password `atlasdev`) and run any of these:
  108. ```cypher
  109. // Show the dependency edges Atlas walks during Ripple
  110. MATCH (downstream)-[r:DEPENDS_ON]->(upstream)
  111. RETURN downstream.kref, upstream.kref, r.dependency_strength
  112. LIMIT 25;
  113. // Show every belief and its current confidence
  114. MATCH (b:Belief)
  115. RETURN b.kref, b.confidence_score, b.deprecated
  116. ORDER BY b.confidence_score DESC;
  117. // Show the AGM revision history of a single belief
  118. MATCH (root:AtlasItem)-[:REVISED_TO|SUPERSEDES*0..]->(rev)
  119. WHERE root.kref = 'kref://AtlasCoffee/Beliefs/origins_value.belief'
  120. RETURN rev.revision_index, rev.content, rev.revision_reason
  121. ORDER BY rev.revision_index;
  122. // Show the contradictions detector found
  123. MATCH (a)-[r:CONTRADICTS]->(b)
  124. RETURN a.kref, b.kref, r.detected_at;
  125. ```
  126. ---
  127. ## Why Atlas exists
  128. The video [*Every Claude Code Memory System Compared*](https://youtu.be/UHVFcUzAGlM) maps 6 levels of memory — from native CLAUDE.md to OpenBrain's cross-tool Postgres. They all answer the same question: *"how do we store and retrieve?"*
  129. **Atlas answers a different question:** *when stored knowledge changes, what happens to everything that depended on it?*
  130. That's a Level 7 problem. Atlas runs ON TOP of any of the 6 lower levels. Every memory system flags affected beliefs when a fact changes. Atlas is the only one that re-evaluates them.
  131. ## What Atlas does that nothing else does
  132. You have a vault. Maybe Obsidian, maybe Notion, maybe just markdown in a folder. Plus your meetings get transcribed (Limitless, Fireflies, Otter), plus your screen gets captured (Screenpipe, Rewind), plus you talk to Claude or ChatGPT all day. Together that's hundreds of files and tens of thousands of facts about your work.
  133. **The problem we focus on:** when one of those facts changes — a price changes, a partner exits, a deadline slips — *every belief that depended on the old fact is now suspect*. Today, you have to chase the cascade in your head. Atlas tries to do it for you.
  134. We're not aware of another open-source system that ships propagation as a first-class primitive; if you know of one, please file an issue — we want to compare honestly.
  135. | When a fact changes... | Typical memory systems | Atlas (alpha) |
  136. |---|---|---|
  137. | Detect what's affected | Vector-similarity heuristic | `Depends_On` graph walk via `RippleEngine.analyze_impact()` |
  138. | Re-evaluate downstream beliefs | Not exposed as a primitive | `RippleEngine.propagate()` — additive-with-damping confidence updates |
  139. | Surface emergent contradictions | Not exposed | Type-aware detector (`atlas_core/ripple/contradiction.py`) |
  140. | Route strategic conflicts to human | Not exposed | Obsidian markdown queue + `adjudication.resolve()` |
  141. | Audit what was decided and why | Limited | Hash-chained SHA-256 ledger with `verify_chain()` |
  142. | Forget deprecated beliefs cleanly | Not exposed | AGM `contract()` removes from closure, preserves history |
  143. Verify any row above by reading the cited module or running `./demo.sh`.
  144. ### The technical claim, for people who care about the math
  145. Atlas implements AGM belief revision (Alchourrón-Gärdenfors-Makinson 1985) on a property graph. The seven postulates K\*2-K\*6 plus Hansson's Relevance and Core-Retainment all hold — verified by 49 scenarios against live Neo4j 5.26. Same compliance Kumiho's commercial paper claims, but as fully open-source local-first code anyone can audit. The full per-scenario reproducibility artifact is at [`docs/AGM_COMPLIANCE.md`](docs/AGM_COMPLIANCE.md) (machine-readable rows in [`benchmarks/agm_compliance/runs/baseline.json`](benchmarks/agm_compliance/runs/baseline.json)).
  146. ### Detailed comparison vs other memory systems
  147. If you're shopping memory backends for an agent system, here's how Atlas stacks up against the named alternatives:
  148. | | Atlas | Kumiho | Graphiti | Mem0 | Letta | Memori |
  149. |---|---|---|---|---|---|---|
  150. | Open-source | ✅ Apache 2.0 | ❌ commercial | ✅ | ✅ | ✅ | ✅ |
  151. | Local-first (no cloud) | ✅ | ❌ requires kumiho.io | ✅ | partial | ✅ | ✅ |
  152. | AGM-compliant revision (K\*2–K\*6) | ✅ 49/49 @ 100% | ✅ 49/49 @ 100% | ❌ | ❌ | ❌ | ❌ |
  153. | Hansson Relevance + Core-Retainment | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
  154. | Hash-chained tamper-detection ledger | ✅ SHA-256 | partial | ❌ | ❌ | ❌ | ❌ |
  155. | **Automatic downstream reassessment (Ripple)** | ✅ | ❌ flag-only | ❌ | ❌ | ❌ | ❌ |
  156. | Domain-typed business ontology shipped | ✅ 8 entity types | ❌ | ❌ | ❌ | ❌ | partial |
  157. | Continuous multi-stream ingestion | ✅ 6 streams | ❌ SDK only | ❌ | ❌ | ❌ | partial |
  158. | Runtime integration | ✅ Claude MCP + native Hermes/OpenClaw/GBrain | partial | ❌ | partial | ❌ | ❌ |
  159. #### What Atlas does *worse* (today)
  160. The table above lists what Atlas does that the alternatives don't. The other half of an honest comparison: here's what they currently do *better*, and where you should reach for them instead of Atlas.
  161. | Concern | What we'd reach for instead | Why |
  162. |---|---|---|
  163. | Pure-retrieval throughput on large corpora | Mem0, a hosted vector DB | Atlas reads embeddings, but the typed graph + Ripple bookkeeping adds latency a vector-only path doesn't pay. If retrieval-quality alone is your bottleneck, a flat vector index will be faster. |
  164. | Conversational chat memory ("remember what I said in this thread") | Letta, Memori | Atlas is built around long-lived business beliefs and dependencies. For "the user mentioned a cat in turn 3, surface that in turn 47" you want a system designed for conversation state. |
  165. | Managed hosted service, support contract, SOC 2 | Kumiho's commercial cloud | Atlas is open-source local-first. There is no "Atlas Inc." with a sales team. If your buying process needs a vendor on the other end, Atlas isn't that yet. |
  166. | Plug-and-play with zero-config setup | Mem0, Letta | Atlas wants you to think about your domain — it ships the AGM operators, not a "just call `add_memory()`" facade. The opinionated typed ontology is power for some users and friction for others. |
  167. | Real-time multi-user concurrency at scale | A managed graph platform (Neo4j Aura, AuraDB) | Atlas's local-first stance means a single Neo4j instance per user. Multi-tenant Tier 5 work is in progress; production-grade concurrency tuning is not the alpha's focus. |
  168. | Natural-language extraction quality on truly unstructured text | LLM-tuned extractors maintained by a larger team | The extractors in `atlas_core/ingestion/extractors/` work on real Limitless / Fireflies / Claude transcripts but quality is uneven — see the alpha framing in the hero. Improving extraction is on the roadmap; if you need state-of-the-art entity extraction *today*, build a richer extraction layer above Atlas's quarantine API. |
  169. If your shopping criteria match any row in the *worse* table, use the alternative. Atlas exists for the case where dependency-driven belief revision is load-bearing — and it's better to admit the tradeoffs than to over-claim and lose your trust the moment you hit one.
  170. ---
  171. ## What Atlas does
  172. Atlas is a Python service that maintains a continuously-updated typed knowledge graph of your domain. Tell it something — directly, or via continuous capture from Screenpipe / Limitless / Fireflies / Claude Code logs / Obsidian / iMessage — and it:
  173. 1. **Quarantines the claim** until corroborated by an independent source family
  174. 2. **Promotes corroborated claims** to a hash-chained append-only ledger
  175. 3. **Triggers Ripple propagation** after a ledger-approved belief is materialized: traverses declared `Depends_On` edges, re-evaluates downstream beliefs with confidence propagation, surfaces emergent contradictions. Atlas does not infer dependency edges from prose; callers declare them through the AGM/MCP surfaces.
  176. 4. **Routes resolution** — reassessments persist as proposals; strategic contradictions also go to a markdown adjudication queue you resolve in Obsidian. Atlas does not claim an automatic proposal consumer until that graph-tier writer ships.
  177. All revisions are AGM-compliant (K\*2–K\*6 + Hansson Relevance + Core-Retainment), formally verified against Kumiho's correspondence theorem (arxiv:2603.17244).
  178. ---
  179. ## Cost ($/month at steady state)
  180. Honest accounting. Atlas's cost story shifts dramatically between v0.1.0a1 (today) and the post-Tier-1 system:
  181. **v0.1.0a1 (today): ≈ $0/month.**
  182. - Extractors are 100% deterministic — frontmatter parsing, YAML readers, regex pattern matching. No LLM calls.
  183. - Ripple's `HeuristicReassessor` (default) does no LLM call; it's a closed-form damped formula. The `LLMReassessor` exists but is opt-in and not the default.
  184. - Portable retrieval uses SQLite only. Native Hermes, OpenClaw, and GBrain can add the bundled
  185. localhost cognitive service for the bounded AGM/Ripple wedge without Docker
  186. or Neo4j. Neo4j 5.26 remains the documented local backend for the broader
  187. property-graph, ledger-projection, MCP, and adjudication stack. No telemetry,
  188. cloud, or API keys are required.
  189. - The only ongoing cost is the electricity to keep your machine on.
  190. **Post-Tier-1.4 (LLM-driven extraction lands): bounded by your token budget.**
  191. - LLM extraction will fire on free-text vault content, transcript bodies, Claude session decisions. The default prompt is sized for Claude Haiku 4.5: ≈ 800 input + 200 output tokens per claim.
  192. - For Rich's actual data (one-author, ~10K events/week): ≈ $0.02-0.05 per claim × ~2K novel claims/week = **$40-100/month** at default settings.
  193. - A token budget knob (`ATLAS_DAILY_LLM_BUDGET_USD`, defaults to $5/day) hard-stops extraction when the daily budget is exceeded. Worst case is $150/month even if the corpus explodes.
  194. - A Ripple cascade triggered by an adjudication.resolve fires *one* LLM call per downstream node when the LLMReassessor is enabled — not per cascade. Rich-scale: <50 cascades/week × ≤10 downstream nodes × ≤$0.05 = **<$25/month** added.
  195. - Total Rich-scale steady state when Tier 1.4 lands: **≈ $50-125/month**, hard-capped by the budget knob.
  196. **Post-Tier-1.3 (entity resolution lands): same dollars, clearer outcomes.**
  197. - The fuzzy + LLM-fallback resolution layer adds roughly $0.001 per ambiguous entity reference. On Rich-scale data, this is bounded by the alias dictionary cache — first-hit each unique alias is ~$0.001, subsequent hits are free.
  198. - Net: rounding error against the extraction cost above.
  199. For multi-tenant deployments (one Neo4j, many trust ledgers — not yet implemented but plausible by 2027), the math scales linearly per active user. A 100-user deployment at Rich-scale per user is ≈ $5K-12K/month in inference, dominantly Haiku.
  200. **The substrate strategy bet:** $50-125/month is below the line where most knowledge workers think twice. It's an order of magnitude cheaper than running Cursor or hosting Mem0's commercial cloud. Atlas's local-first design is the architectural reason this number stays small.
  201. ---
  202. ## Real-world performance
  203. On a one-author corpus (Rich Schefren's actual Obsidian vault + 5,000 Limitless transcripts + 300 Screenpipe audio rows + 5,000 Claude Code session logs):
  204. ```
  205. == Atlas first real run ==
  206. Streams : 4
  207. Total events : 10,604
  208. Total claims : 14,674
  209. Total errors : 0
  210. Elapsed : 21.3s
  211. Quarantine status breakdown:
  212. requires_approval 6,761 (medium-risk default; awaits adjudication)
  213. Quarantine lane breakdown:
  214. atlas_observational 5,608 (Limitless + Screenpipe)
  215. atlas_vault 956 (vault frontmatter + body)
  216. atlas_chat_history 197 (Claude session prompts)
  217. Ledger intact: ✅ (SHA-256 chain verified)
  218. ```
  219. Re-runs are idempotent: 0.9s for the next cycle, with all duplicate claims fingerprint-deduplicated against existing entries.
  220. ---
  221. ## Quickstart (3 minutes)
  222. > Three good install paths depending on why you want Atlas — researcher / dev, Obsidian power-user, or agent-runtime integration. Each one is self-contained and documented in [`docs/INSTALL_MODES.md`](docs/INSTALL_MODES.md). The block below is the universal version that works for all three.
  223. ```bash
  224. # 1. Clone
  225. git clone https://github.com/RichSchefren/atlas && cd atlas
  226. # 2a. Prove portable Hermes/OpenClaw storage + retrieval (no Docker)
  227. python -m venv .venv && source .venv/bin/activate
  228. pip install -e .
  229. PYTHONPATH=. python scripts/demo_runtime_adapters.py
  230. # 2b. Native Hermes: install its managed cognitive service (no Docker)
  231. bash integrations/hermes-atlas/install.sh
  232. # 2c. Or install the native OpenClaw / GBrain cognitive package
  233. bash integrations/openclaw-atlas/install.sh
  234. bash integrations/gbrain-atlas/install.sh
  235. # 2d. Optional broader property-graph/MCP/adjudication tier
  236. docker compose up -d # bolt://localhost:7687
  237. # 3. Install — base is deterministic + $0/month; opt in to extras as you need them
  238. pip install -e . # core: AGM + Ripple + ledger + adapters + ingest
  239. # pip install -e ".[llm]" # add Anthropic SDK for LLM-driven extraction
  240. # pip install -e ".[embeddings]" # add sentence-transformers (~2GB; rarely needed — vault-search is the default retrieval path)
  241. # pip install -e ".[benchmarks]" # add Mem0 / Letta clients for the BMB matrix
  242. # pip install -e ".[full]" # everything above
  243. # pip install -e ".[dev]" # contributor tooling (includes anthropic for tests)
  244. # 4. Verify with the test suite (532 tests in this snapshot)
  245. PYTHONPATH=. pytest tests/ -v
  246. # 5. Reproduce AGM compliance (49/49 scenarios, ~30s)
  247. PYTHONPATH=. pytest tests/integration/test_agm_compliance.py -v
  248. # 6. First real ingest from your own Obsidian vault
  249. ATLAS_VAULT_ROOT=~/Documents/Obsidian PYTHONPATH=. python scripts/first_real_run.py
  250. # 6b. Multiple vaults (colon-separated, like PATH) — e.g. a shared business
  251. # vault plus a personal vault feeding one belief graph
  252. ATLAS_VAULT_ROOTS=~/Vaults/business:~/Vaults/personal PYTHONPATH=. python scripts/first_real_run.py
  253. ```
  254. ---
  255. ## Architecture
  256. ```
  257. ┌──────────────────────────────────────────────────────────────┐
  258. │ ATLAS API LAYER │
  259. │ MCP (13 tools) · FastAPI (:9879) · Kumiho-compatible gRPC │
  260. │ + Hermes / OpenClaw cores + Claude Code MCP │
  261. └──────────────────────────────────────────────────────────────┘
  262. │
  263. ┌──────────────────────────────────────────────────────────────┐
  264. │ RIPPLE ENGINE — Atlas's novel contribution │
  265. │ AnalyzeImpact → Reassess → Type-aware Contradictions → │
  266. │ Adjudication routing (auto / strategic / core-protected) │
  267. └──────────────────────────────────────────────────────────────┘
  268. │
  269. ┌──────────────────────────────────────────────────────────────┐
  270. │ TRUST LAYER — Quarantine → Corroboration → Hash-chained │
  271. │ Ledger. SHA-256 chain with verify_chain() tamper detection. │
  272. └──────────────────────────────────────────────────────────────┘
  273. │
  274. ┌──────────────────────────────────────────────────────────────┐
  275. │ AGM REVISION — K*2–K*6 + Hansson, Cypher-backed │
  276. │ 49/49 compliance scenarios pass at 100% │
  277. └──────────────────────────────────────────────────────────────┘
  278. │
  279. ┌──────────────────────────────────────────────────────────────┐
  280. │ ATLAS CORE — fork of Graphiti │
  281. │ Bitemporal edges. 6 Kumiho typed edges + 8 domain entities │
  282. └──────────────────────────────────────────────────────────────┘
  283. │
  284. ┌──────────────────────────────────────────────────────────────┐
  285. │ CONTINUOUS INGESTION — 6 streams, idempotent cursors │
  286. │ Vault · Limitless · Screenpipe · Claude · Fireflies · iMsg │
  287. └──────────────────────────────────────────────────────────────┘
  288. ```
  289. Full design docs are checked into the repo at [`paper/atlas.md`](paper/atlas.md) and [`PHASE-5-AND-BEYOND.md`](PHASE-5-AND-BEYOND.md). The deeper Phase 0 / Phase 1 specs live in the maintainer's private notes — public summaries are in the paper draft.
  290. ---
  291. ## API surfaces
  292. Atlas ships with three concurrent surfaces:
  293. - **MCP**: 17 Atlas-original tools — the graph/Ripple, adjudication, quarantine, ledger, working-memory, lineage, and sharing tools plus portable `memory.search`, `memory.get`, `memory.list`, and `memory.forget`. Stdio JSON-RPC bridge for Claude Code via `python -m atlas_core.adapters.claude_code`. Read-only vs mutation classification at [`docs/PROPOSAL_VS_MUTATION.md`](docs/PROPOSAL_VS_MUTATION.md).
  294. - **HTTP**: FastAPI on `localhost:9879` mirrors the MCP surface for non-MCP clients. `/health` is public; every data or mutation route requires `Authorization: Bearer $(cat ~/.atlas/http-token)`. Browser access is limited to an explicit origin allowlist (`ATLAS_HTTP_ALLOWED_ORIGINS`). Endpoints: `/health`, `/tools`, `/tools/{name}`, `/verify-chain`, `/events`.
  295. - **Portable cognitive HTTP**: the authenticated, single-scope localhost v1
  296. service in `integrations/cognitive-service/`. Native Hermes, OpenClaw, and
  297. the GBrain bridge manage this
  298. sidecar automatically; it is separate from the broader FastAPI/MCP server so
  299. host clients cannot accidentally inherit Neo4j or Atlas's broader dependencies.
  300. - **gRPC** (Phase 2 W7+): scaffold with all 51 Kumiho-compatible RPC method names registered. Existing Kumiho SDK code switches to Atlas by setting `endpoint="localhost:50051"`.
  301. Plus runtime adapters:
  302. - `atlas_core.adapters.claude_code` — MCP stdio bridge for Claude Code
  303. - `atlas_core.adapters.hermes.AtlasHermesProvider` — functional SQLite-backed Hermes-shaped core
  304. - `atlas_core.adapters.openclaw.AtlasOpenClawPlugin` — functional SQLite-backed OpenClaw-shaped core
  305. - `integrations/hermes-atlas/` — native current-Hermes `MemoryProvider` plugin
  306. - `integrations/openclaw-atlas/` — native current-OpenClaw TypeScript memory plugin
  307. - `integrations/gbrain-atlas/` — independent GBrain MCP-to-Atlas cognitive bridge
  308. See [`docs/RUNTIME_ADAPTERS.md`](docs/RUNTIME_ADAPTERS.md) for the portable
  309. core/native package boundary and proof matrix.
  310. ---
  311. ## Benchmarks
  312. Atlas is benchmarked head-to-head with Kumiho, Graphiti, Mem0, Letta, Memori, MemPalace, and vanilla GPT-4o (no memory) on three suites:
  313. ### 1. AGM compliance — 49 / 49 at 100%
  314. Operational verification (not symbolic) of AGM postulates K\*2–K\*6 plus Hansson Relevance + Core-Retainment. Same scenario count as Kumiho's published Table 18.
  315. | Postulate | Scenarios | Passed | Pass rate |
  316. |----------------------------|-----------|--------|-----------|
  317. | K\*2 Success | 12 | 12 | 100.0% |
  318. | K\*3 Inclusion | 8 | 8 | 100.0% |
  319. | K\*4 Vacuity | 1 | 1 | 100.0% |
  320. | K\*5 Consistency | 9 | 9 | 100.0% |
  321. | K\*6 Extensionality | 3 | 3 | 100.0% |
  322. | Relevance (Hansson) | 7 | 7 | 100.0% |
  323. | Core-Retainment (Hansson) | 9 | 9 | 100.0% |
  324. | **Total** | **49** | **49** | **100.0%** |
  325. Five scenario categories — simple (10), multi_item (8), chain (8), temporal (8), adversarial (15). Adversarial bucket includes deliberately constructed cycles, conflicting tags, and concurrent revision races; all pass. Reproducible in one command:
  326. ```bash
  327. PYTHONPATH=. pytest tests/integration/test_agm_compliance.py -v
  328. ```
  329. Full scenario-level table: [`paper/appendix-a-agm-compliance.md`](paper/appendix-a-agm-compliance.md).
  330. ### 2. BusinessMemBench — Atlas 1.000, Graphiti 0.711, Vanilla 0.000 (preliminary, self-authored)
  331. > 📦 **BMB now ships as its own repo:** [github.com/RichSchefren/businessmembench](https://github.com/RichSchefren/businessmembench) (MIT, `pip install businessmembench`). Adopt it, run it on your memory system, publish your numbers. Atlas's in-tree copy stays as a vendored snapshot for zero-dep test runs.
  332. > ⚠ **Honesty disclaimer.** BusinessMemBench is *authored by the Atlas project*. The 149 questions in the current set are *deterministic and synthetic* — generated from corpus templates, not written by independent domain operators. Mem0, Letta, Memori, Kumiho, and MemPalace columns are still **skipped** because their API clients aren't pinned in this environment. We're publishing these numbers because the test loop reproduces on every machine that runs `scripts/run_bmb.py`, but **you should not treat them as a peer-reviewed head-to-head until the 200 human-authored gold subset and the four skipped baselines have actually run**. The full disclosure of what's authored vs measured is in `paper/atlas.md` § 6.2.
  333. Currently 149 deterministic questions across three paraphrase variants per template. The 200 human-authored gold subset and LLM expansion to 1,000 are roadmap.
  334. | System | status | overall | prop | contra | line | cross | hist | prov | forget |
  335. |---------------------|----------|---------|------|--------|------|-------|------|------|--------|
  336. | Vanilla (no memory) | measured | 0.000 | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 |
  337. | Graphiti | measured | 0.711 | 0.33 | 0.00 | 1.00 | 0.00 | 1.00 | 1.00 | 0.00 |
  338. | **Atlas** | measured | **1.000** | **1.00** | **1.00** | **1.00** | **1.00** | **1.00** | **1.00** | **1.00** |
  339. | Mem0 | skipped | — | — | — | — | — | — | — | — |
  340. | Letta | skipped | — | — | — | — | — | — | — | — |
  341. | Memori | skipped | — | — | — | — | — | — | — | — |
  342. | Kumiho | skipped | — | — | — | — | — | — | — | — |
  343. | MemPalace | skipped | — | — | — | — | — | — | — | — |
  344. `measured` = adapter wired in this repo, ran on this machine, score is from `baseline_seed42.json`.
  345. `skipped` = adapter wired but the run requires credentials / pip install we don't ship (e.g. `OPENAI_API_KEY`, `MEMORI_API_KEY`, the `kumiho-sdk` package). Each adapter raises a clear `MissingClientError` with the missing dependency. Atlas does not bundle external API keys.
  346. Atlas's structural lead over Graphiti — the contradiction / cross_stream / forgetfulness / propagation columns — is what the architecture was designed for. The score gap on a self-authored deterministic benchmark proves the architecture works against its own thesis; it does not yet prove general superiority. Reproducible in ≤30 seconds:
  347. ```bash
  348. PYTHONPATH=. python scripts/run_bmb.py
  349. ```
  350. The canonical run output (`seed=42`, full matrix) is checked in at [`benchmarks/business_mem_bench/runs/baseline_seed42.json`](benchmarks/business_mem_bench/runs/baseline_seed42.json) so visitors can read the scores without installing anything. The structural claims above are also enforced by `tests/integration/test_bmb_endtoend.py` — if Atlas regresses below 1.0 on any category, or Graphiti unexpectedly perfect-scores a Ripple category, CI fails loudly.
  351. ### 3. LoCoMo / LongMemEval — claimed parity, NOT YET MEASURED
  352. > ⚠ The runners exist (`benchmarks/locomo/runner.py`, `benchmarks/longmemeval/runner.py`) and pass their own structural tests. The actual datasets — research-license JSONL files from the LongMemEval and LoCoMo papers — have **not** been downloaded and run against Atlas yet. The "parity with Kumiho's published 0.447 F1" claim is therefore an architectural prediction, not a measurement. The paper marks every cell in this category as predicted-not-measured.
  353. ---
  354. ## Testers
  355. If you want to break Atlas, [TESTING.md](TESTING.md) has five concrete paths from a 5-minute smoke test to a 30-minute wire-level deep dive. Findings get filed via structured GitHub issue templates that auto-route by area (`smoke-test`, `loop-demo`, `bench`, `claude-code`, `ingest`). CI watches every push at <https://github.com/RichSchefren/atlas/actions>.
  356. ---
  357. ## Status — surgical separation of works today vs planned
  358. **Alpha — v0.1.0a1.** Codex's review (2026-04-27) recommended this section be unambiguous. Every "works today" row below has a one-line proof you can run in under 10 seconds.
  359. ### Works today (verified by tests in CI)
  360. | Capability | Proof |
  361. |---|---|
  362. | `RippleEngine.propagate()` runs the full cascade end-to-end | `./demo.sh` |
  363. | AGM compliance — K\*2 / K\*3 / K\*4 / K\*5 / K\*6 / Hansson Relevance / Core-Retainment | `pytest tests/integration/test_agm_compliance.py -v` (49/49) |
  364. | Versioned SHA-256 ledger that hash-binds content and audit fields, with legacy-chain verification | `pytest tests/unit/test_ledger.py -v` |
  365. | Trust quarantine → corroboration → ledger state machine | `pytest tests/unit/test_quarantine.py -v` |
  366. | Six ingestion extractors (Vault, Limitless, Screenpipe, Claude sessions, Fireflies stub, iMessage) | `pytest tests/unit/test_ingestion.py tests/unit/test_ingestion_extra.py -v` |
  367. | Entity resolution cascade (alias → fuzzy → LLM fallback) | `pytest tests/unit/test_resolution.py -v` |
  368. | LLM-driven extraction with hard-capped daily budget | `pytest tests/unit/test_llm_extractors.py -v` |
  369. | Decision-lineage walker + lineage-weakening contradiction detector | `pytest tests/integration/test_lineage.py -v` |
  370. | Working-memory block manager (Letta-style) | `pytest tests/unit/test_working_memory.py -v` |
  371. | Multi-tenant tenant context + sharing policy + federated adjudication | `pytest tests/unit/test_multi_tenant.py -v` |
  372. | Adjudication round-trip — markdown queue → AGM revise → ledger SUPERSEDE → archive | `pytest tests/integration/test_adjudication_resolver.py -v` |
  373. | 17 MCP tools dispatch correctly via stdio JSON-RPC | `pytest tests/integration/test_mcp_server.py tests/integration/test_claude_code_stdio.py -v` |
  374. | Bearer-authenticated FastAPI surface with allowlisted CORS + Server-Sent Events | `pytest tests/unit/test_http_server_security.py tests/integration/test_http_server.py tests/unit/test_events_broadcaster.py -v` |
  375. | Ledger-approved graph materialization triggers Ripple once per ledger event | `pytest tests/unit/test_materializer_ripple.py tests/integration/test_candidate_materialization.py -v` |
  376. | Hermes/OpenClaw adapter storage, retrieval, fetch, list, and forget without Neo4j | `python scripts/demo_runtime_adapters.py` |
  377. | Native OpenClaw host cognition and GBrain page-linked cognition | `.github/workflows/openclaw-native.yml` and `.github/workflows/gbrain-native.yml` |
  378. | Kumiho-compat gRPC handlers (10 of 51 methods wired, 41 return UNIMPLEMENTED) | `pytest tests/integration/test_grpc_handlers.py -v` |
  379. | Property-based AGM testing (hypothesis-driven) | `pytest tests/unit/test_agm_property_based.py -v` |
  380. | BusinessMemBench at 1.000 vs Graphiti 0.711 on 149 deterministic questions | `python scripts/run_bmb.py` |
  381. | Live ingest from real machine state (vault + Limitless + Screenpipe + Claude) | `python scripts/first_real_run.py` |
  382. | launchd daemon installs (continuous ingestion + API server) | `./scripts/install_launchd.sh` |
  383. | **All of the above run together** | `pytest tests/ -v` (532 passing) |
  384. ### Planned — explicitly NOT done (no proof commands, by design)
  385. | Capability | Why it's not done |
  386. |---|---|
  387. | LoCoMo + LongMemEval **measured** numbers (not asserted) | Datasets are research-license; haven't been downloaded + run yet. Runners exist (`benchmarks/locomo/`, `benchmarks/longmemeval/`); just need someone with dataset access to fire them. |
  388. | Mem0 / Letta / Memori columns in BMB matrix | Adapters fail-loud without `OPENAI_API_KEY` / `MEMORI_API_KEY`. Set the keys + re-run `scripts/run_bmb.py` to fill the rows. |
  389. | 1,000-question BusinessMemBench (currently 149 deterministic) | The 200 human-authored gold subset (templates in `benchmarks/business_mem_bench/gold_human/`) needs domain-operator authors. The remaining 800 are LLM-expanded from templates — runner ready, expansion not yet executed. |
  390. | arxiv submission live | Tarball ready at `paper/arxiv/atlas-arxiv.tar.gz`. Submission goes through arxiv.org/submit (24-48h moderation). |
  391. | Confidence-threshold empirical calibration | Script exists at `scripts/calibrate_confidence_thresholds.py`. Needs a week of real ingest data before it produces a meaningful recommendation. |
  392. | Obsidian plugin in the Community Plugins registry | Plugin code complete at `obsidian-plugin/`. Manual install path documented; registry submission deferred. |
  393. | MCP plugin registry submission | Manifest at `mcp-registry/atlas.json`. Submitted when MCP registry opens for plugin uploads. |
  394. If a row in **Works today** doesn't actually work on your machine, that's a bug — file an issue using the `tester-smoke` template.
  395. If a row in **Planned** is something you want sooner, file an issue describing the use case and we'll prioritize.
  396. Atlas as v0.1.0a1 is roughly **70-80% of the full system** described in the Phase 0 design docs. See `PHASE-5-AND-BEYOND.md` for the tiered roadmap of what's left.
  397. Test count this snapshot: **532 passing** locally against Python 3.14 + Neo4j 5.26; the pull-request matrix independently verifies Python 3.10–3.14 and Windows.
  398. ---
  399. ## License
  400. Apache 2.0. See [LICENSE](LICENSE).
  401. BusinessMemBench (the benchmark dataset) is MIT — maximally permissive for adoption as the new evaluation reference for propagation-aware memory systems.
  402. ---
  403. ## Acknowledgments
  404. Atlas implements the AGM correspondence proofs from **Young Bin Park, *Graph-Native Cognitive Memory for AI Agents*** (arxiv:2603.17244, 2026). Atlas is an independent open-source implementation; not affiliated with Kumiho Inc.
  405. Forks the storage substrate from **Graphiti by Zep AI** (Apache 2.0). Trust layer ports the policy architecture from **Bicameral by yhl999** (Apache 2.0); the SHA-256 hash chain is Atlas-original (Bicameral's chain was aspirational).
  406. Built with multi-model AI collaboration: Claude Opus 4.7 (architecture, algorithms, paper), Codex 5.5 (boilerplate + tests), Gemini 2.5 Pro (parallel design review).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.