agentic-memory

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

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.