agentos-memory

Memory is not the product. Learning is. The atomic unit of value is the Experience = knowledge + context + outcome.

AgentOS gives your agents a memory that learns: it reflects on each run, distills durable experiences, generalizes them into best practices and failure patterns, and serves the most useful knowledge back — with a recommended, guard‑railed plan — for the next task.

---

Why AgentOS

Most "agent memory" is a vector store: it remembers text. AgentOS is different — it learns from outcomes.

• Experience‑centric — every execution becomes a structured Experience (what worked, why, when it applies).
• Blended usefulness ranking — retrieval ranks on similarity + empirical usefulness, confidence, reward, and recency — not cosine alone.
• Learns across runs — repeated successes → best practices; repeated failures → failure patterns you can plan around.
• Plans, not just recalls — plan() synthesizes prior experience into concrete steps + guardrails derived from past failures.
• Bring your own LLM — Ollama (local), OpenAI‑compatible, and Anthropic (Claude). Per‑engine routing.
• Runs anywhere — the same API embedded (SQLite/numpy) or self‑hosted (FastAPI + Qdrant/Postgres/Redis).

Install

pip install agentos-memory                      # core   (import stays `import agentos`)
pip install "agentos-memory[ollama,cli]"        # + local models + CLI
pip install "agentos-memory[server]"            # + FastAPI server (Qdrant/Postgres/Redis)
pip install "agentos-memory[mcp]"               # + MCP server for coding agents (Claude Code/Cursor/Roo…)
pip install "agentos-memory[chroma]"            # BYO vector store (also: [pgvector], [pinecone])

Quickstart (embedded, local)

AgentOS requires a real LLM provider — a local model via Ollama or a cloud model with your own key. There are no mock providers.

ollama serve
ollama pull llama3.1:8b
ollama pull nomic-embed-text

from agentos import AgentOS, Execution

memory = AgentOS(
    path="./agent_memory",
    llm={
        "reflection": {"provider": "ollama", "model": "llama3.1:8b"},
        "learning":   {"provider": "ollama", "model": "llama3.1:8b"},
        "planning":   {"provider": "ollama", "model": "llama3.1:8b"},
        "embeddings": {"provider": "ollama", "model": "nomic-embed-text"},
    },
)

memory.learn(Execution(task="Deploy app", output="ok", status="success"))
memory.flush()                              # let async reflection settle (scripts only)
result = memory.retrieve("deploy an app")   # most useful experiences
plan = memory.plan("deploy an app safely")  # recommended approach + guardrails

Cloud models (bring your own key)

# OpenAI (or any OpenAI-compatible endpoint via base_url)
memory = AgentOS(path="./mem", llm={
    "reflection": {"provider": "openai", "model": "gpt-4o-mini", "api_key": "sk-..."},
    "embeddings": {"provider": "openai", "model": "text-embedding-3-small"},
})

# Anthropic (Claude) — for reasoning, paired with a local embeddings model
memory = AgentOS(path="./mem", llm={
    "reflection": {"provider": "anthropic", "model": "claude-sonnet-4-20250514", "api_key": "..."},
    "learning":   {"provider": "anthropic", "model": "claude-sonnet-4-20250514"},
    "planning":   {"provider": "anthropic", "model": "claude-sonnet-4-20250514"},
    "embeddings": {"provider": "ollama", "model": "nomic-embed-text"},
})

Auto‑capture with @remember

Wrap any function so each call is learned from automatically — successes and failures:

from agentos.integrations import remember

@remember(memory)
def resolve_ticket(ticket: str) -> str:
    ...

Framework adapters are included for LangChain, CrewAI, LlamaIndex, and OpenAI Agents.

Coding agents (MCP) — memory that persists across sessions

Give Claude Code, Cursor, Roo Code, Cline, Windsurf, or Codex a persistent, per‑repository memory. One integration works with every MCP client: the agent calls recall before a task and learn after, so knowledge carries across sessions and tools.

pip install "agentos-memory[mcp]"    # provides the `agentos-mcp` stdio server

// e.g. Cursor .cursor/mcp.json — see agentos/mcp/examples for every client
{
  "mcpServers": {
    "agentos": { "command": "agentos-mcp", "env": {} }
  }
}

Tools: recall, learn, record_failure, plan, search_memory, status, and visualize (opens the dashboard for the current repo). Memory is auto‑scoped per repo (git remote → folder). Add the AGENTS.md snippet so agents use it habitually. Full guide: agentos/mcp/README.md.

Per‑user memory (chatbots)

Building a chatbot? Give each end‑user their own private memory — and a short‑term conversation buffer — with the same verbs. Pass user_id and knowledge learned for that user stays private to them; shared knowledge (no user_id) is visible to everyone.

# Learn a private preference for one user
memory.learn(Execution(
    task="preference",
    output="Alice prefers window seats and vegetarian meals.",
    status="success", user_id="alice",
))

# Recall folds in the user's private memory + shared knowledge
memory.recall("what are my seat preferences?", user_id="alice")   # sees Alice's
memory.recall("what are my seat preferences?", user_id="bob")     # does NOT
memory.recall("refund policy")                                    # shared only

Short‑term working memory — a TTL'd, per‑session rolling buffer of turns (distinct from long‑term experiences), backed by the KV store:

memory.remember_turn("user", "Book me a flight to Tokyo",
                     user_id="alice", session_id="chat-42")
memory.remember_turn("assistant", "Sure — window or aisle?",
                     user_id="alice", session_id="chat-42")

memory.render_working_memory(user_id="alice", session_id="chat-42")  # prompt-ready
memory.clear_working_memory(user_id="alice", session_id="chat-42")   # on reset

user_id is an orthogonal axis to org→project→agent tenancy: privacy is enforced in the TenancyGuard, so a user never sees another user's private memory, and an anonymous request never sees any user's private memory.

Bring your own vector store (RAG builders)

Already have a vector DB? Point AgentOS at it — AgentOS adds the memory + learning layer (experiences, GraphRAG, usefulness ranking) on top of your existing store instead of owning one. Every driver implements the same VectorStore contract, so the engines are unchanged.

# Chroma (embedded/persistent or a remote server)
memory = AgentOS(path="./mem", storage={"vector": {"driver": "chroma", "path": "./chroma"}})

# Postgres + pgvector (one DB for metadata + vectors)
memory = AgentOS(path="./mem", storage={
    "vector": {"driver": "pgvector", "url": "postgresql://user:pw@host:5432/db"}})

# Pinecone (managed; AgentOS collections → namespaces in one index)
memory = AgentOS(path="./mem", storage={
    "vector": {"driver": "pinecone", "api_key": "...", "index_name": "agentos"}})

# Qdrant
memory = AgentOS(path="./mem", storage={"vector": {"driver": "qdrant", "url": "http://localhost:6333"}})

Supported vector drivers: numpy (embedded default), qdrant, pgvector, chroma, pinecone. Install the matching extra (agentos[pgvector|chroma|pinecone]). Storage is per‑concern — you can swap only the vector store and keep the rest embedded. See docs/12-storage-plug-and-play.md.

Self‑host + dashboard

agentos server start                 # FastAPI on :6333
agentos console start                # Next.js dashboard on :3000

The console makes the learning loop visible: an Experiences browser, a Retrieval Explorer with per‑signal score breakdowns, a Learning view (best practices + failure patterns), and interactive 3D Vector Space and Knowledge Graph visualizations.

CLI

agentos init
agentos models pull llama3.1:8b
agentos config set-llm --provider ollama --model llama3.1:8b
agentos retrieve "deploy shopify app"
agentos plan "deploy shopify app"
agentos server start
agentos console start

Architecture

Six engines behind a small, tier‑agnostic core:

Everything sits behind pluggable interfaces:

• Storage — VectorStore, MetadataStore, GraphStore, KVStore, BlobStore. Embedded drivers ship today (SQLite, numpy, filesystem); server + BYO drivers plug in behind the same contract — vectors: Qdrant, pgvector, Chroma, Pinecone; metadata: Postgres; KV: Redis.
• LLM — LLMProvider: OllamaProvider (local), OpenAIProvider (OpenAI / vLLM / Azure / any OpenAI-compatible), AnthropicProvider (Claude), GeminiProvider (Google Gemini). Mix per engine (e.g. Claude for reasoning + Ollama for embeddings).

Reflection & Learning run asynchronously on a durable in‑process JobQueue.

See docs/ for the full project, technical, SDK, backend, and deployment docs.

Tests

Deterministic unit tests (storage, ranking, tenancy, queue, config) run without any LLM:

pip install -e ".[dev]"
pytest
ruff check .

Contributing

Contributions are welcome! Please read CONTRIBUTING.md and our CODE_OF_CONDUCT.md. Security issues: see SECURITY.md.

License & Open‑core

AgentOS is open source under Apache‑2.0. The embedded SDK, the intelligence verbs, framework adapters, the CLI, the self‑hosted server, and the dashboard are all free and open.

A commercial Enterprise tier (SSO/RBAC, audit, managed cloud, priority support) is available for teams that need it — see ENTERPRISE.md and the OSS‑vs‑Enterprise matrix in docs/10-open-core.md.