rootmemory 0.1.0__py3-none-any.whl

rootmemory-0.1.0.dist-info/METADATA

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: rootmemory
+Version: 0.1.0
+Summary: Provenance-aware memory for multi-agent AI systems: tells corroboration apart from repetition
+Author-email: Shubham Ambavane <ambavane26@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Shubs5758/RootMemory
+Project-URL: Repository, https://github.com/Shubs5758/RootMemory
+Project-URL: Issues, https://github.com/Shubs5758/RootMemory/issues
+Project-URL: Documentation, https://github.com/Shubs5758/RootMemory#readme
+Keywords: ai,agents,multi-agent,memory,provenance,langgraph,langchain,knowledge-graph,evidence
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: structlog>=24.1
+Provides-Extra: api
+Requires-Dist: fastapi>=0.115; extra == "api"
+Requires-Dist: uvicorn[standard]>=0.30; extra == "api"
+Requires-Dist: alembic>=1.13; extra == "api"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2; extra == "langgraph"
+Requires-Dist: langchain-core>=0.3; extra == "langgraph"
+Provides-Extra: llm
+Requires-Dist: openai>=1.30; extra == "llm"
+Provides-Extra: all
+Requires-Dist: fastapi>=0.115; extra == "all"
+Requires-Dist: uvicorn[standard]>=0.30; extra == "all"
+Requires-Dist: alembic>=1.13; extra == "all"
+Requires-Dist: psycopg[binary]>=3.1; extra == "all"
+Requires-Dist: langgraph>=0.2; extra == "all"
+Requires-Dist: langchain-core>=0.3; extra == "all"
+Requires-Dist: openai>=1.30; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+# RootMemory
+
+**Provenance-aware memory for multi-agent AI systems. It tells corroboration apart from repetition.**
+
+[![PyPI](https://img.shields.io/pypi/v/rootmemory.svg)](https://pypi.org/project/rootmemory/)
+[![Python](https://img.shields.io/pypi/pyversions/rootmemory.svg)](https://pypi.org/project/rootmemory/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+```bash
+pip install rootmemory
+```
+
+## The problem
+
+A customer writes *"we're targeting October, but the date isn't final."*
+
+```
+Agent A reads the email  ->  "the deadline is October 15"
+Agent B reads Agent A    ->  "the deadline is October 15"
+Agent C reads Agent B    ->  "the deadline is October 15"
+```
+
+Your shared memory now shows three agents agreeing. There is still only **one**
+source, and it did not say that. Every belief traces back to the same email —
+but a list of conclusions has forgotten that, so the system counts three votes
+and acts.
+
+RootMemory keeps those numbers apart:
+
+```
+agreeing agents            3
+supporting beliefs         3
+independent evidence roots 1   <- the only number that reflects reality
+```
+
+## Quick start
+
+```python
+from rootmemory import RootMemory, open_memory
+
+with open_memory("sqlite+pysqlite:///memory.db") as session:
+    memory = RootMemory(session)
+
+    research = memory.register_agent("ResearchAgent")
+    risk     = memory.register_agent("RiskAgent")
+    exec_    = memory.register_agent("DecisionAgent")
+
+    # evidence from the outside world
+    article = memory.create_observation("news", "Revenue may have slipped.")
+
+    # three agents, but only the first one read the article
+    b1 = memory.create_belief(research.id, "Supplier under pressure.", "risk", 0.6, [article])
+    b2 = memory.create_belief(risk.id,     "Supplier is unstable.",     "risk", 0.8, [b1])
+    b3 = memory.create_belief(exec_.id,    "Significant risk.",         "risk", 0.85, [b2])
+
+    claim = memory.get_or_create_claim("risk", "Supplier is in distress.")
+    for belief in (b1, b2, b3):
+        memory.support_claim(claim.id, belief.id)
+
+    verdict = memory.evaluate_claim(claim.id)
+```
+
+```
+agreeing agents          3
+supporting beliefs       3
+independent sources      1
+decision                 REJECT
+why                      3 supporting beliefs descend from a single evidence source.
+```
+
+Add a genuinely separate source and it promotes. That is the entire idea.
+
+## How it works
+
+Four objects, one rule.
+
+| Object | What it is |
+| --- | --- |
+| **Observation** | evidence from outside. Immutable — only its validity can change. |
+| **Belief** | what an agent concluded. Must cite what it came from. |
+| **Claim** | a proposition beliefs support or contradict. |
+| **Decision** | an action taken because of a claim. |
+
+**The rule: every belief must say what it was derived from.** RootMemory refuses
+to store one that cites nothing. That turns memory into a family tree, so any
+belief can be walked back to the real-world evidence at the bottom.
+
+A claim enters shared memory only through the **promotion gate**, which counts
+independent evidence roots — never agreeing agents. Contradictions are
+preserved rather than overwritten. And retracting a source walks *forward*
+through everything built on it: beliefs are retracted, claims downgraded,
+dependent decisions flagged `needs_review`.
+
+## Plugging into a framework
+
+The core imports no agent framework. Adapters are optional extras.
+
+### LangChain / LangGraph long-term memory
+
+```bash
+pip install "rootmemory[langgraph]"
+```
+
+```python
+from langchain.agents import create_agent
+from rootmemory.integrations.langgraph_store import RootMemoryStore
+
+agent = create_agent(model=..., tools=[...], store=RootMemoryStore(agent_id=risk_id))
+```
+
+`BaseStore.put` has nowhere to say *"here is what I read first"*, so the adapter
+infers it: the store remembers what it served to that agent and cites it as the
+parents of whatever it writes next. Provenance capture with no cooperation from
+the model.
+
+### Tools that force citation
+
+```python
+from rootmemory.integrations.langchain_tools import build_tools
+model = model.bind_tools(build_tools(memory, agent_id))
+```
+
+`derived_from` is a **required** field in the tool schema, so a model cannot
+record an opinion without saying what it read.
+
+### LangGraph nodes
+
+```python
+from rootmemory.integrations.langgraph_memory import MemoryState, remembering
+
+graph.add_node("risk", remembering(memory, risk_id, claim_key="supplier_risk")(assess))
+```
+
+State carries belief ids, not just text — text has forgotten where it came from.
+
+### Anything else
+
+`AsyncRootMemory` is plain async Python with no framework types in its
+signatures. Non-Python agents can use the REST API.
+
+## Optional extras
+
+| Extra | Adds |
+| --- | --- |
+| `rootmemory[api]` | FastAPI service, Alembic migrations, and the visual portal at `/ui` |
+| `rootmemory[langgraph]` | LangGraph store, node wrapper, LangChain tools |
+| `rootmemory[postgres]` | PostgreSQL driver |
+| `rootmemory[llm]` | LLM-backed claim normalization |
+| `rootmemory[all]` | everything |
+
+The core depends only on SQLAlchemy, Pydantic and structlog. Importing the
+memory engine will not drag in a web framework.
+
+## The portal
+
+```bash
+pip install "rootmemory[api]"
+rootmemory serve
+```
+
+Open <http://localhost:8000/ui>. Observations form the floor and everything
+built on them stacks above, so an echo chain renders as a tall thin tower on a
+single foundation. Click any node to trace it back to the evidence it actually
+came from; everything off that path dims.
+
+## Design rules
+
+* Every belief has at least one causal parent. No provenance, no shared memory.
+* Observations are never edited or deleted, only marked invalid.
+* Only the promotion service may confirm a claim.
+* Contradictions are preserved, never overwritten.
+* Graph cycles are refused.
+* Agreement count and independent-evidence count are always reported separately.
+* The core is deterministic. An LLM may write belief text; it never decides what
+  counts as evidence.
+
+## Measured against a naive shared scratchpad
+
+Same beliefs, same confidences, same thresholds — the baseline just has no
+ancestry to consult.
+
+| Metric | RootMemory | Shared scratchpad |
+| --- | --- | --- |
+| False corroboration rate | **0.0** | 0.25 |
+| Wrong-action rate | **0.0** | 0.5 |
+| Promotion precision | **1.0** | 0.5 |
+| Repair completeness | **1.0** | 0.0 |
+
+Cost: roughly 5–6x more rows, because the family tree is kept alongside the
+conclusions.
+
+## Documentation
+
+* [Running it](docs/running.md) — step-by-step, including the demo and portal
+* [Architecture](docs/architecture.md) — the four algorithms in detail
+* [API reference](docs/api.md)
+* [Deployment](docs/deployment.md) — config, auth, claim normalization, rollout
+* [Evaluation](docs/evaluation.md) — generated benchmark results
+
+## Status
+
+Working, tested MVP: 144 tests, type-checked and linted. Runs on SQLite with no
+server. PostgreSQL is supported and its migration renders correct DDL, but has
+not yet been exercised against a live server.
+
+## License
+
+MIT

rootmemory-0.1.0.dist-info/RECORD

@@ -0,0 +1,75 @@
+rootmemory/__init__.py,sha256=2Xl_Kllzi93yjmB9QjGxCMO0oRPGy5INeliSCyzwUPg,2493
+rootmemory/cli.py,sha256=eYmSlxtlllpdfEYjQjbZzeIeCsWiLwU4vDfgML1wk8o,2788
+rootmemory/client.py,sha256=05WPhY4FL97rRSAhh23LlWYxbGC0lP2WfECr5gFwONE,9161
+rootmemory/config.py,sha256=WwWy5NducPlm5ppZwsrhiSqT-fWW1RgcHsPyZXe4fOo,2425
+rootmemory/errors.py,sha256=G52GTYYm0RaIsM7TDYzZoAEa8AMnba99SxwFnxowi9A,828
+rootmemory/logging_config.py,sha256=hprZJcgi8d3LevC4OgL3oLHc6AaE5TEj5lw-wYENnM0,955
+rootmemory/main.py,sha256=tlEbR1M5xf-o092TC8DSr6yh-4877Sf6XFmx8_x8RWw,4405
+rootmemory/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rootmemory/api/__init__.py,sha256=FpmKC4OGtPqHb-IZxC1ZJBX8_oRmK2QEpdPvuCjNM9k,450
+rootmemory/api/agents.py,sha256=bRTIEst0m8_-uUWLS4_p-pzJ8H_9yL8fjq4ktN5kKIY,1271
+rootmemory/api/beliefs.py,sha256=745G1iysyo_A9yw2Rz9FIVqdrH2qzrr3sRiMOHj433s,2603
+rootmemory/api/claims.py,sha256=Th9ekzm1tIqtg0uufE3bI4NecWUqGTV0dkUCFdD6s74,3442
+rootmemory/api/deps.py,sha256=nRowDSU-xTtoGohJdP2yhBD-WS-JeAVjpgMGfQ5JO-s,508
+rootmemory/api/errors.py,sha256=DlvD-GDo4TSbvQ-QAKvh6q1810AJdnaepZs6KZUMBIc,1109
+rootmemory/api/graph.py,sha256=St0qc0HZ2hrE9Gc9S2DeAQWjmGZGey_E2sfFS45mfvA,1134
+rootmemory/api/invalidation.py,sha256=aMZfopV9BunQR1KVfpdWGgGIiKKP2ubeIPcf3BjSFNs,1787
+rootmemory/api/observations.py,sha256=LtwJZ74-K1D5t-zanb_zGbtq_vp2OJy29TAxj66ej1g,1835
+rootmemory/api/promotion.py,sha256=0tvp0ZzDwRcD4ZLzyP-Vaaq18tN04O0v86Gh9zwYScs,1618
+rootmemory/api/provenance.py,sha256=LAkunI0ty-lMrdLm4fBY5VKECqXZhy455eP4x0uVkVc,3298
+rootmemory/api/security.py,sha256=Bg6cnWAylOTxTcHsHIG2k3H6mSwF_JG9K-O-KaQpQs8,1895
+rootmemory/db/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rootmemory/db/base.py,sha256=I95-c-9e3KGVLsfz6k0V3c7PzwHbl_Ge94QCQ1o1c7I,1296
+rootmemory/db/session.py,sha256=ZZlMtyvVRJZBrOOcHTmGJRkQTpn2W4T4gkRf5yYj5co,4531
+rootmemory/db/migrations/env.py,sha256=rxUiy1G3-ly9jPl_IhL3qoaY35pEw89nQKRvqaCavZQ,1696
+rootmemory/db/migrations/script.py.mako,sha256=0ykYGifheMDY3x5NZv0u221fTFHS3tGM3n8TpqMnPC8,615
+rootmemory/db/migrations/versions/d336d5cf7fb9_initial_schema.py,sha256=HxayCbP3C4N1ZJCuquSbbQQATocCPLu4r_MB0AZuTgE,14735
+rootmemory/integrations/__init__.py,sha256=MKg7I8vqdmdoWMNzjnL1vcT4EURBkroNRLQv2BAzXig,767
+rootmemory/integrations/async_client.py,sha256=bDh3LfXYtheXsnyhaZOCj9A1TgeHuGEeClkKbiPpWA0,10186
+rootmemory/integrations/langchain_tools.py,sha256=v3Rw7my7t0xQGn9qLYEg2iGiXRpHkLGMNTlqeqPKueA,9198
+rootmemory/integrations/langgraph_memory.py,sha256=KZh8zxlabHTAwpBApc8ZrRTUvkyUW9-w4MCtoDjzueo,6687
+rootmemory/integrations/langgraph_store.py,sha256=oz55Tizc8OizkosSaxATafkmLA-kYqo-MWnuHTnLCdc,16513
+rootmemory/models/__init__.py,sha256=0RMX11Uqt-pOL1eOjMj_JDc0CTH-Bi1q9GPMY57nG1Q,673
+rootmemory/models/agent.py,sha256=c0D3-ssMy-n0HAYDrPj_7HDB7vTbDsEJcNDwSlmkcR8,1061
+rootmemory/models/audit.py,sha256=dGb4qWT63UwEeAWvJI226gvTJijbG2sMaWZJUoKJxdQ,2313
+rootmemory/models/belief.py,sha256=aBgY5bVe6W83Qw-lQmsjl8sAYDOz3T4OBFsV_RYZSjU,1629
+rootmemory/models/claim.py,sha256=BVjtRZWcUHqqOUlDemsTYAMg1DGYA3QlXte0LJo-yDE,2234
+rootmemory/models/decision.py,sha256=qA_TrjVxOb2Au0Hw4DDlxgcLT2PohcOK_zLVc_ENYtk,1519
+rootmemory/models/edge.py,sha256=7fTi_e1As6CBDhKul-wSwrZKDhkPrXr6ktTrYgJgjso,1681
+rootmemory/models/enums.py,sha256=aWPxSABBsCmUcX-aFHxKdpUpNP7kcwmUZYOZ7Ix2qp4,2881
+rootmemory/models/node_ref.py,sha256=MRUOYJ0eX3blAyo8PxUFbNTg_aGGMkLXP3HnNwAK25M,1163
+rootmemory/models/observation.py,sha256=jd6ja1QqzOvhKGD96r0w7URUgNwhiztPiRKVizc80vw,2174
+rootmemory/repositories/__init__.py,sha256=4V-XHHwFFL4DRdO6dLRZhqNanKdwE5UFASoKj9U78oQ,727
+rootmemory/repositories/agent_repo.py,sha256=DEmjawljXdgCxZHczcbUG_VCPQRmcH9soRjLEk97bww,1221
+rootmemory/repositories/audit_repo.py,sha256=vVMjGC3rpws1x8TKlPH-htWF9fa6CXjUicfEc2kZe7w,1431
+rootmemory/repositories/belief_repo.py,sha256=EQErnpcNRhPh_Xatb7HnBgeVj5rDfL_1773nSNzInQQ,2207
+rootmemory/repositories/claim_repo.py,sha256=9USBw5a7_LEfMMQN6jEXfZ4WLL11RM_G2AcaKcl9COk,3969
+rootmemory/repositories/decision_repo.py,sha256=sThZ4HSuAA_opYKXX_wKbq6UkSXi1YoUKAKvvIveGVw,2665
+rootmemory/repositories/edge_repo.py,sha256=48WSGxGvQSpgO5j-Ld0k5KDnCJZTAyHthcGuXHK9Rgo,2842
+rootmemory/repositories/observation_repo.py,sha256=aZOBMU0CLfIlmUeftjfthpoPA12SBl-n9ylpOj9Hedc,2705
+rootmemory/schemas/__init__.py,sha256=jUjRjAHnWH-FNzW9SbBBz1b-XgT349zASAJ8ttvK8Yw,1404
+rootmemory/schemas/agent.py,sha256=bWjGOScO33RURZE_rnbapmAPnTHqKrFur1fEBzQr0QI,563
+rootmemory/schemas/belief.py,sha256=HMQHReLDbHY4MLnUfNl97h6iBS9012trEeVZ4OO_Q98,1385
+rootmemory/schemas/claim.py,sha256=FdtfdTjpf5nXWvq6Qp9msAu-brWRB38AIx-CJyR82MI,1364
+rootmemory/schemas/common.py,sha256=diVdM7OZ3KChRwZIE3VspXzfEoJx1-inyIQWd_f-8xI,603
+rootmemory/schemas/observation.py,sha256=akzHxD-ipgAD1hJ9o_Eeiko_6h-1DGPL6Gv3BXIPr68,1953
+rootmemory/schemas/promotion.py,sha256=fhMhXOGUD_B04SK-jkxgTEChXXtYnm4F6_Oh7mcoYcg,1352
+rootmemory/schemas/provenance.py,sha256=2p10tsV9IC80kWVT-J8ZzulhfEttOyr9UsWwzpfI9mk,1434
+rootmemory/services/__init__.py,sha256=j400xFyJh4tML9oTPA5a5AGpvHijjAUQiTCbrxbaCi4,1132
+rootmemory/services/belief_service.py,sha256=hjsScTJFbVtcTFiUf8kJ2f49VeZqubkWf8BTOexN_QM,6340
+rootmemory/services/contradiction_service.py,sha256=Iry30qvCfNit3qMf5N14F5D3PTsV-jeqWmjFaUzLxzA,6511
+rootmemory/services/decision_service.py,sha256=5ltUkD_oGL0uNGai5atawyZWPmo6FOcw3Z-MkaXYAD4,2679
+rootmemory/services/graph_service.py,sha256=qEu_01x4pClI7SOIYlxsTeqwh4pdErAjW1u0UXZXvSw,12919
+rootmemory/services/independence_service.py,sha256=-bpGK_BPtDs4Ut8BykNkUMsH3Lx4rDtTeNhiCmwVZzc,6563
+rootmemory/services/invalidation_service.py,sha256=rSBhKCozfas-d8qRscXHVa9ttLRwXiGfQNK5KCdRC_M,7169
+rootmemory/services/normalization_service.py,sha256=D5KkK8uIZ-U1r1m9kOwhD5hUKd7UTTEz7Y8HzOGrwgo,9656
+rootmemory/services/promotion_service.py,sha256=gE9CGfApEJ00w-tw3ipoG2ZmQCzqY3jMpD1LAaZwK1M,13910
+rootmemory/services/provenance_service.py,sha256=mRw4Z88T6Gh1wFRL97yXvqe7qJwjMuBRvlr9GxgFcUU,11855
+rootmemory/services/scoring_service.py,sha256=SExXRW_DlF6uqfgJU5J24MVIJOPr-B-PW2b9tXFFyXI,1788
+rootmemory/static/index.html,sha256=Gc57Mbtm19zIGrr3F6iPy4XrRkiFQEvluWjHNN0Cu-w,33152
+rootmemory-0.1.0.dist-info/licenses/LICENSE,sha256=WIDyXIUqkcXJWy_ejPCZvpleD7FowfPQPPSwuAnA-H0,1073
+rootmemory-0.1.0.dist-info/METADATA,sha256=fEWoEwoBadSXE-PA2lflsBY-Sae0bxOTzfBshp7K7Y0,9830
+rootmemory-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+rootmemory-0.1.0.dist-info/entry_points.txt,sha256=zWQW9781PlNJmCmBd3PYn9_lmQg0LR4QRAea_QMIANw,51
+rootmemory-0.1.0.dist-info/top_level.txt,sha256=LdyFVegI0XXgoMokQ0P29np5zZ61fzEZOLvhsyFeVIM,11
+rootmemory-0.1.0.dist-info/RECORD,,

rootmemory-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rootmemory-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rootmemory = rootmemory.cli:main

rootmemory-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shubham Ambavane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rootmemory-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rootmemory