ContextOS
A Graph-Theoretic Memory Kernel for Agentic AI Systems
"Beyond RAG: Stateful memory for AI agents that actually remembers."
What is ContextOS?
ContextOS is a framework for building AI agents with persistent, structured memory. Unlike standard RAG (Retrieval-Augmented Generation) which treats documents as flat vectors, ContextOS models memory as a graph where:
- Nodes are memories (semantic facts, episodic events, procedural rules)
- Edges encode relationships (temporal, causal, associative)
- Retrieval uses hybrid scoring:
PageRank centrality + Vector similarity
This enables multi-hop reasoning that pure vector search cannot achieve.
Key Features
- 🧠 CoALA Memory Architecture - Semantic, Episodic, and Procedural memory types
- 🔗 Graph-Native Storage - NetworkX topology + ChromaDB vectors
- ⚡ Hybrid Retrieval - PageRank centrality × semantic similarity
- 💾 Persistent by Default - Memory survives restarts
- 🔌 LangChain Compatible - Works with any LLM provider
Installation
pip install agentic-memory
Or from source:
git clone https://github.com/ARYAN2302/ContextOS.git
cd context-os
pip install -e .
Quick Start
Simple API (Recommended)
from agentic_memory import ContextClient, MemoryType
# Initialize (loads existing memory if available)
client = ContextClient()
# Add memories
client.add_memory("User prefers dark mode", MemoryType.SEMANTIC)
client.add_memory("User asked about Python yesterday", MemoryType.EPISODIC)
# Compile context for a query
context = client.compile("What are the user's preferences?")
print(context)
Full Chat Loop
from agentic_memory import ContextClient
client = ContextClient()
def my_llm(system_prompt: str, user_query: str) -> str:
# Your LLM call here (OpenAI, Groq, Anthropic, etc.)
return llm.invoke(system_prompt + user_query)
# Run a full RAG loop with automatic memory logging
response = client.chat("What should I work on today?", llm_callable=my_llm)
Low-Level API
from agentic_memory import ContextGraph, ContextNode, ContextEdge, MemoryType, ContextCompiler
# Direct graph access
kernel = ContextGraph()
node = ContextNode(content="Important fact", type=MemoryType.SEMANTIC)
kernel.add_node(node)
# Add relationships
edge = ContextEdge(source=node1.id, target=node2.id, relation="CAUSES")
kernel.add_edge(edge)
# Compile context
compiler = ContextCompiler(kernel)
context = compiler.compile("query", token_budget=500, alpha=50, beta=50)
Architecture
context_os/
├── client.py # ContextClient - main entry point
├── core/
│ ├── schema.py # Pydantic models (ContextNode, ContextEdge, MemoryType)
│ └── graph.py # Hybrid storage (NetworkX + ChromaDB)
├── memory/
│ ├── ingestor.py # LLM-powered memory classification
│ └── compiler.py # PageRank + Vector hybrid retrieval
└── utils/
└── text.py # Text processing utilities
The Hybrid Scoring Formula
relevance(node, query) = (α × semantic_similarity) + (β × pagerank_centrality × time_decay)
- α (alpha): Weight for semantic similarity (vector search)
- β (beta): Weight for graph centrality (structural importance)
- time_decay: Recency factor for episodic memories
Benchmarks
Needle-in-a-Haystack (NIAH)
ContextOS retrieves a "needle" fact from 100+ distractor memories with 100% recall.
cd experiments && python niah_benchmark.py
Ablation Study
| Configuration | Multi-Hop Accuracy |
|---|---|
| Vector Only (RAG) | 50% |
| Graph Only | 50% |
| ContextOS (Hybrid) | 100% |
Configuration
client = ContextClient(
storage_path="my_memory.json", # Graph persistence
chroma_path="my_vectors/", # Vector store
auto_persist=True # Save on every change
)
# Retrieval tuning
context = client.compile(
query="...",
token_budget=1000, # Max tokens in context
alpha=50.0, # Vector weight
beta=50.0 # Graph weight
)
Requirements
- Python 3.10+
- NetworkX
- ChromaDB
- Sentence-Transformers
- Pydantic
- LangChain (optional, for LLM integration)
License
MIT License - See LICENSE for details.
Acknowledgments
Inspired by the CoALA architecture for cognitive agents.
Metadata
Release files for agentic-memory 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentic_memory-0.1.2.tar.gz | 12.8 kB | Without provenance | Details for agentic_memory-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentic_memory-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for agentic_memory-0.1.2-py3-none-any.whl |
Total release size: 24.7 kB
Release files / agentic_memory-0.1.2.tar.gz
| Download URL | agentic_memory-0.1.2.tar.gz |
|---|---|
| Size | 12.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ced9386f4e228e083567649bd472b4f46a0c0ed5c2902a1dca5df71f12032674
|
|
BLAKE2b-256 checksum How to use checksums |
a2d33c0483bf8995254faac1686bbd982ba195efe2032033b10b0378812a58b6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.7
|
Release files / agentic_memory-0.1.2-py3-none-any.whl
| Download URL | agentic_memory-0.1.2-py3-none-any.whl |
|---|---|
| Size | 11.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e5a0d4842917e685ac97fd28e31bb19f003923fbd29cb285481d10b043903f25
|
|
BLAKE2b-256 checksum How to use checksums |
ef2cee9474e6a56de5283a2e5c5e60273ba29b2e65d56869e08be8a86a049b18
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.7
|
Security for agentic-memory 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.