Metadata-Version: 2.5
Name: agentos-memory
Version: 0.1.0
Summary: The operating memory and learning runtime for AI agents — turn every execution into reusable intelligence.
Project-URL: Homepage, https://agentos.ai
Project-URL: Documentation, https://agentos.ai/docs
Project-URL: Repository, https://github.com/nivera-ai/AgentOS
Project-URL: Issues, https://github.com/nivera-ai/AgentOS/issues
Project-URL: Changelog, https://github.com/nivera-ai/AgentOS/blob/main/CHANGELOG.md
Author: AgentOS
License: Apache-2.0
License-File: LICENSE
Keywords: agentic,agents,ai,experience,learning,llm,memory,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: pydantic>=2.5
Requires-Dist: typing-extensions>=4.8
Provides-Extra: all
Requires-Dist: httpx>=0.25; extra == 'all'
Requires-Dist: langchain-core>=0.1; extra == 'all'
Requires-Dist: mcp>=2.0; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Requires-Dist: rich>=13.0; extra == 'all'
Requires-Dist: typer>=0.9; extra == 'all'
Provides-Extra: anthropic
Provides-Extra: chroma
Requires-Dist: chromadb>=0.4; extra == 'chroma'
Provides-Extra: cli
Requires-Dist: rich>=13.0; extra == 'cli'
Requires-Dist: typer>=0.9; extra == 'cli'
Provides-Extra: crewai
Requires-Dist: crewai>=0.1; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1; extra == 'langchain'
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.10; extra == 'llamaindex'
Provides-Extra: mcp
Requires-Dist: mcp>=2.0; extra == 'mcp'
Provides-Extra: ollama
Requires-Dist: httpx>=0.25; extra == 'ollama'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Provides-Extra: openai-agents
Requires-Dist: openai-agents>=0.1; extra == 'openai-agents'
Provides-Extra: pgvector
Requires-Dist: psycopg[binary]>=3.1; extra == 'pgvector'
Provides-Extra: pinecone
Requires-Dist: pinecone-client>=3.0; extra == 'pinecone'
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == 'server'
Requires-Dist: psycopg[binary]>=3.1; extra == 'server'
Requires-Dist: qdrant-client>=1.7; extra == 'server'
Requires-Dist: redis>=5.0; extra == 'server'
Requires-Dist: uvicorn>=0.27; extra == 'server'
Description-Content-Type: text/markdown

<div align="center">

# AgentOS

**The operating memory and learning runtime for AI agents.**
Turn every execution into reusable intelligence that continuously improves future autonomous work.

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org)
[![PyPI](https://img.shields.io/pypi/v/agentos.svg)](https://pypi.org/project/agentos/)
[![CI](https://github.com/nivera-ai/AgentOS/actions/workflows/ci.yml/badge.svg)](https://github.com/nivera-ai/AgentOS/actions/workflows/ci.yml)
[![Tests](https://img.shields.io/badge/tests-51%20passing-brightgreen.svg)](tests/)

</div>

> 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

```bash
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](https://ollama.com) or a cloud
model with your own key. There are no mock providers.

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

```python
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)

```python
# 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:

```python
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.

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

```jsonc
// 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](agentos/mcp/examples/AGENTS.snippet.md) so agents use it
habitually. Full guide: [`agentos/mcp/README.md`](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.

```python
# 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:

```python
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`](agentos/storage/base.py) contract, so the engines are unchanged.

```python
# 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`](docs/12-storage-plug-and-play.md).

## Self‑host + dashboard

```bash
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

```bash
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:

| Engine | Role |
|--------|------|
| **Memory** | persist experiences across vector / metadata / graph / KV / blob |
| **Retrieval** | return the *most useful* experiences (blended ranking, not cosine alone) |
| **Reflection** | turn one execution → an experience (LLM, schema‑constrained) |
| **Learning** | many experiences → best practices, failure patterns, workflows |
| **Planning** | recommend an approach using experiences + best practices + failures |
| **Org Intelligence** | scope + share across Org → Project → Agent |

Everything sits behind **pluggable interfaces**:
- **Storage** — [`VectorStore`](agentos/storage/base.py), [`MetadataStore`](agentos/storage/base.py), [`GraphStore`](agentos/storage/base.py), [`KVStore`](agentos/storage/base.py), [`BlobStore`](agentos/storage/base.py). 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`](agentos/llm/base.py): [`OllamaProvider`](agentos/llm/local/ollama.py) (local), [`OpenAIProvider`](agentos/llm/cloud/openai_provider.py) (OpenAI / vLLM / Azure / any OpenAI-compatible), [`AnthropicProvider`](agentos/llm/cloud/anthropic_provider.py) (Claude), [`GeminiProvider`](agentos/llm/cloud/gemini_provider.py) (Google Gemini). Mix per engine (e.g. Claude for reasoning + Ollama for embeddings).

Reflection & Learning run **asynchronously** on a durable in‑process [`JobQueue`](agentos/queue.py).

See [`docs/`](docs/README.md) for the full project, technical, SDK, backend, and deployment docs.

## Tests

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

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

## Contributing

Contributions are welcome! Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) and our
[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). Security issues: see [`SECURITY.md`](SECURITY.md).

## License & Open‑core

AgentOS is **open source under [Apache‑2.0](LICENSE)**. 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`](ENTERPRISE.md) and the OSS‑vs‑Enterprise matrix in
[`docs/10-open-core.md`](docs/10-open-core.md).
