Metadata-Version: 2.4
Name: core-memory
Version: 1.1.0
Summary: Persistent causal agent memory with lossless compaction
Author-email: John Inniger <john@linelead.io>
Maintainer-email: John Inniger <john@linelead.io>
License: Apache-2.0
Project-URL: Homepage, https://github.com/JohnnyFiv3r/Core-Memory
Project-URL: Repository, https://github.com/JohnnyFiv3r/Core-Memory
Project-URL: Issues, https://github.com/JohnnyFiv3r/Core-Memory/issues
Keywords: memory,agent,causal,beads,compaction
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: http
Requires-Dist: fastapi; extra == "http"
Requires-Dist: uvicorn; extra == "http"
Requires-Dist: httpx; extra == "http"
Provides-Extra: pydanticai
Requires-Dist: pydantic-ai; extra == "pydanticai"
Provides-Extra: semantic
Requires-Dist: numpy; extra == "semantic"
Requires-Dist: faiss-cpu; extra == "semantic"
Provides-Extra: tokenizer
Requires-Dist: tiktoken; extra == "tokenizer"
Provides-Extra: openai
Requires-Dist: openai; extra == "openai"
Requires-Dist: numpy; extra == "openai"
Requires-Dist: faiss-cpu; extra == "openai"
Requires-Dist: tiktoken; extra == "openai"
Provides-Extra: qdrant
Requires-Dist: qdrant-client; extra == "qdrant"
Provides-Extra: chromadb
Requires-Dist: chromadb; extra == "chromadb"
Provides-Extra: pgvector
Requires-Dist: psycopg[binary]; extra == "pgvector"
Provides-Extra: langchain
Requires-Dist: langchain-core; extra == "langchain"
Provides-Extra: crewai
Requires-Dist: crewai; extra == "crewai"
Provides-Extra: neo4j
Requires-Dist: neo4j; extra == "neo4j"
Provides-Extra: encryption
Requires-Dist: cryptography; extra == "encryption"
Provides-Extra: all
Requires-Dist: fastapi; extra == "all"
Requires-Dist: uvicorn; extra == "all"
Requires-Dist: httpx; extra == "all"
Requires-Dist: pydantic-ai; extra == "all"
Requires-Dist: numpy; extra == "all"
Requires-Dist: faiss-cpu; extra == "all"
Requires-Dist: openai; extra == "all"
Requires-Dist: neo4j; extra == "all"
Dynamic: license-file

<p align="center">
 <img src="docs/assets/core-memory-hero-banner.jpg" alt="Core Memory" width="100%" />
</p>

<p align="center">
 <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="Apache-2.0 License"></a>
 <a href="#"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
</p>

<p align="center">
 <b>Causal memory for AI agents.</b><br>
 Structured memory objects + causal trace over durable events — so agents can recall <i>why</i>, not just <i>what</i>.
</p>

<p align="center">
 <a href="#install">Install</a> ·
 <a href="#fastest-paths">Fastest Paths</a> ·
 <a href="#service-mode-springai--http">Service Mode</a> ·
 <a href="#current-status">Current Status</a> ·
 <a href="docs/architecture_overview.md">Architecture</a> ·
 <a href="docs/public_surface.md">Public Surface</a> ·
 <a href="#contributing">Contributing</a> ·
 <a href="#maintainers">Maintainers</a>
</p>

---

## Reviewer Quick Path

1. `core-memory --root ./memory setup init`
2. `CORE_MEMORY_CANONICAL_SEMANTIC_MODE=degraded_allowed PYTHONPATH=. python3 examples/canonical_5min.py`
3. `PYTHONPATH=. python3 examples/proof_carry_forward.py`
4. `PYTHONPATH=. python3 -m eval.reviewer_quick_value_v2 --root ./memory --strict`

Optional follow-up telemetry (proxy-style, not full strategy replay benchmark):
- `PYTHONPATH=. python3 -m eval.dreamer_behavior_eval --root ./memory --since 30d`
- `PYTHONPATH=. python3 -m eval.longitudinal_benchmark_v2 --root ./memory --since 30d`

Then use:
- [docs/reviewers/start-here.md](docs/reviewers/start-here.md)
- [docs/contributor_map.md](docs/contributor_map.md)
- [docs/canonical_surfaces.md](docs/canonical_surfaces.md)
- [docs/architecture_overview.md](docs/architecture_overview.md)
- [docs/integrations/](docs/integrations/) (OpenClaw / PydanticAI / SpringAI / LangChain / Neo4j shadow graph)

## Current Status

- **Canonical surfaces:** `process_turn_finalized` / `process_session_start` / `process_flush` + `search` / `trace` / `execute`
- **Adapter helper ingress:** `emit_turn_finalized(...)` remains supported for bridge/integration adapters
- **Compatibility surfaces:** archived or non-primary docs/modules retained for migration/history only
- **Experimental areas:** optional adapters and evaluation harnesses that are useful but not yet hard product contract
- **Not yet integrated:** ideas/proposals not represented in canonical docs or adapter references are intentionally out of current contract scope

## Product Contract (Plain English)

If you're new here, this is the shortest trust contract for what is stable now:

- **Required (core product):**
  - write memory with `process_turn_finalized(...)`
  - read memory with `memory search|trace|execute` (or Python equivalents)
- **Recommended for most users:**
  - keep `CORE_MEMORY_CANONICAL_SEMANTIC_MODE=degraded_allowed` on base installs
  - install `core-memory[semantic]` when you want strict semantic retrieval behavior
- **Compatibility (supported, not primary):**
  - direct `MemoryStore` workflows
  - legacy CLI aliases like `recall ...`
- **Experimental / adapter-specific:**
  - optional integrations and eval harnesses that are not listed as canonical surfaces

If a feature is not in this contract or `docs/public_surface.md`, treat it as non-primary.

### 30-second tier map (mandatory vs optional)

- **Required**
  - base install: `pip install core-memory`
  - canonical write boundary: `process_turn_finalized(...)`
  - canonical retrieval: `memory search|trace|execute` (or Python equivalents)
- **Recommended**
  - semantic extras: `pip install "core-memory[semantic]"`
  - strict semantic retrieval mode (`CORE_MEMORY_CANONICAL_SEMANTIC_MODE=required`) when you need hard semantic guarantees
- **Compatibility (supported, not primary)**
  - `MemoryStore` direct workflows
  - adapter helper ingress `emit_turn_finalized(...)`
- **Experimental / optional extensions**
  - Neo4j shadow adapter (visualization/inspection)
  - eval harnesses under `eval/`

### Plain-English glossary for first-touch terms

- **canonical semantic mode** → strict semantic retrieval mode
- **`degraded_allowed`** → allow lexical fallback if semantic backend is missing
- **companion service** → optional HTTP service mode
- **hydration** → load source details after selecting retrieval results

---

## Live Demo

<p align="center">
 <a href="https://youtu.be/56uyTJEnOAA">
 <img src="docs/assets/core-memory-live-demo-still.jpg" alt="Core Memory live demo (click to watch on YouTube)" width="100%" />
 </a>
</p>

[Watch the Core Memory live demo on YouTube](https://youtu.be/56uyTJEnOAA)

---

## What Is Core Memory?

Most agent memory systems store *what happened*. Core Memory stores **why it happened**.

It records structured memory events called **beads** — decisions, lessons, outcomes, evidence, context — and the causal links between them. When an agent asks “why did we change strategy?”, Core Memory retrieves a decision chain, not just keyword matches.

### Why use it?

| Approach | Failure Mode | Core Memory |
|---|---|---|
| Chat log replay | Context window explodes | Bounded rolling window with compaction |
| Vector similarity | “Similar” ≠ “relevant” | Semantic-first anchors + causal trace over explicit bead links |
| Tool call logs | No reasoning structure | Explicit bead → bead associations |

**Core local write flow has zero required runtime dependencies beyond Python.**
Query-based anchor lookup in canonical mode requires semantic backend support (or explicit degraded mode opt-in).
Optional extras exist for HTTP service mode and integration-specific workflows.

---

## Install

### From PyPI

```bash
pip install core-memory
```

### From source

```bash
git clone https://github.com/JohnnyFiv3r/Core-Memory.git
cd Core-Memory
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .
```

### Optional extras

Semantic backend extras (recommended for canonical query path):

```bash
pip install "core-memory[semantic]"
```

If you want provider-backed semantic embeddings, install the matching client library in the same Python environment. For example, OpenAI-backed semantic retrieval needs:

```bash
pip install openai
```

HTTP companion service:

```bash
pip install "core-memory[http]"
```

PydanticAI adapter:

```bash
pip install "core-memory[pydanticai]"
```

Neo4j shadow graph adapter (visualization/inspection only):

```bash
pip install "core-memory[neo4j]"
```

Developer/test extras:

```bash
pip install "core-memory[dev]"
```

---

## Fastest Paths

### 1) Smallest believable product path (5 minutes)

No adapters, no direct `MemoryStore` calls, canonical boundaries only.

```bash
core-memory --root ./memory setup init

# Base install path (no semantic extras)
export CORE_MEMORY_CANONICAL_SEMANTIC_MODE=degraded_allowed
python3 - <<'PY'
from core_memory import process_turn_finalized, memory_execute

root = "./memory"
process_turn_finalized(
    root=root,
    session_id="five-minute",
    turn_id="t1",
    user_query="What should we do about Redis timeouts?",
    assistant_final="Decision: increase pool size to 200.",
)
out = memory_execute(
    request={"raw_query": "why redis timeouts", "intent": "causal", "k": 5},
    root=root,
    explain=True,
)
print({
    "ok": out.get("ok"),
    "degraded": out.get("degraded", False),
    "result_count": len(out.get("results") or []),
})
PY
```

Expected output:
- `ok: true`
- a non-zero `result_count`
- `degraded: true` is acceptable in this base-install path

If you want strict canonical semantic mode instead:

```bash
pip install "core-memory[semantic]"
unset CORE_MEMORY_CANONICAL_SEMANTIC_MODE
python3 - <<'PY'
from core_memory import process_turn_finalized, memory_execute

root = "./memory"
process_turn_finalized(
    root=root,
    session_id="five-minute",
    turn_id="t1",
    user_query="What should we do about Redis timeouts?",
    assistant_final="Decision: increase pool size to 200.",
)
out = memory_execute(
    request={"raw_query": "why redis timeouts", "intent": "causal", "k": 5},
    root=root,
    explain=True,
)
print({
    "ok": out.get("ok"),
    "degraded": out.get("degraded", False),
    "result_count": len(out.get("results") or []),
})
PY
```

Source-checkout equivalent example script:

```bash
PYTHONPATH=. python3 examples/canonical_5min.py
```

### 2) Canonical Python runtime/retrieval path

```python
from core_memory import process_turn_finalized, memory_execute

root = "./memory"

process_turn_finalized(
 root=root,
 session_id="s1",
 turn_id="t1",
 user_query="Why did Redis fail?",
 assistant_final="Decision: increase Redis pool to 200 to prevent exhaustion.",
)

out = memory_execute(
 request={"raw_query": "why redis", "intent": "causal", "k": 5},
 root=root,
 explain=True,
)

print(out.get("ok"), len(out.get("results") or []))
```

### 3) CLI retrieval surface

Once memory exists, canonical retrieval CLI is:

```bash
core-memory --root ./memory memory search --query "redis pool"
core-memory --root ./memory memory trace --query "why redis pool"
core-memory --root ./memory memory execute --request '{"raw_query":"why redis","intent":"causal","k":5}'
```

### 4) Compatibility store API (advanced / direct persistence)

`MemoryStore` remains available for direct persistence workflows and migrations,
but it is not the primary canonical runtime path.

See:
- `examples/store_compat_quickstart.py`

---

## Service Mode (SpringAI / HTTP)

For JVM, JS/TS-adjacent, or service-oriented architectures, run Core Memory as a companion HTTP service.

### Start the service

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[http]"
python3 -m core_memory.integrations.http.server
```

Equivalent startup command:

```bash
python3 -m uvicorn core_memory.integrations.http.server:app --host 0.0.0.0 --port 8000
```

Optional auth:

```bash
export CORE_MEMORY_HTTP_TOKEN="change-me"
```

### Verify the service

```bash
curl http://localhost:8000/healthz
```

```bash
curl -X POST http://localhost:8000/v1/memory/execute \
 -H "Content-Type: application/json" \
 -d '{
 "request": {
 "raw_query": "why did we change strategy?",
 "intent": "causal",
 "k": 5
 },
 "explain": true
 }'
```

### SpringAI write path

Send finalized assistant turns to:

- `POST /v1/memory/turn-finalized`

Minimum useful fields:

- `session_id`
- `turn_id`
- `user_query`
- `assistant_final`

Session lifecycle boundaries:

- `POST /v1/memory/session-start` (explicit session-start snapshot boundary)
- `POST /v1/memory/session-flush` (session-end flush boundary)
- `GET /v1/memory/continuity` (pure-read continuity payload; no implicit writes)

### SpringAI runtime path

Preferred single-call endpoint:

- `POST /v1/memory/execute`

This is the best fit for service-oriented orchestration where a backend needs one deterministic memory call instead of multiple client-side routing steps.

See also:

- [docs/integrations/springai/quickstart.md](docs/integrations/springai/quickstart.md)
- [docs/integrations/springai/integration-guide.md](docs/integrations/springai/integration-guide.md)
- [docs/integrations/springai/api-reference.md](docs/integrations/springai/api-reference.md)

---

## Integrations

### Canonical ingress port

```python
from core_memory import process_turn_finalized
```

Adapter/helper ingress remains available for bridge code:

```python
from core_memory.integrations.api import emit_turn_finalized
```

### Available integration surfaces

- OpenClaw bridge
- PydanticAI native adapter
- SpringAI / HTTP companion service
- LangChain (`CoreMemory`, `CoreMemoryRetriever`)
- Neo4j shadow graph adapter (projection-only visualization/inspection)

### Good starting points

- **Canonical first-touch**
  - [examples/canonical_5min.py](examples/canonical_5min.py)
  - [examples/quickstart.py](examples/quickstart.py)
- **Recommended value proofs**
  - [examples/proof_carry_forward.py](examples/proof_carry_forward.py)
  - [eval/reviewer_quick_value_v2.py](eval/reviewer_quick_value_v2.py)
- **Recommended integration starts**
  - [examples/pydanticai_basic.py](examples/pydanticai_basic.py)
  - [docs/integrations/springai/quickstart.md](docs/integrations/springai/quickstart.md)
  - [docs/integrations/langchain/quickstart.md](docs/integrations/langchain/quickstart.md)
  - [docs/integrations/neo4j/quickstart.md](docs/integrations/neo4j/quickstart.md)
- **Compatibility**
  - [examples/store_compat_quickstart.py](examples/store_compat_quickstart.py)

---

## How It Works

<p align="center">
 <img src="docs/assets/core-memory-architecture-new.png" alt="Core Memory Architecture — Retrieval and Write sides" width="100%" />
</p>

Core Memory separates **retrieval** from **writes**, connected through session-scoped bead storage. Each agent turn follows the same loop:

1. **Inject** — build a bounded context packet
2. **Execute** — run the agent turn
3. **Extract** — capture structured events as beads
4. **Store** — append to durable session/event surfaces
5. **Compact** — preserve important causal memory, compress the rest
6. **Recall** — retrieve causal chains when the agent needs them

---

## Core Concepts

### Beads

A bead is a structured memory event: decision, lesson, outcome, evidence, context, or another typed unit of recall.

### Associations

Associations are explicit links between beads and remain queryable even as memory compacts.

### Retrieval Pipeline

Canonical retrieval surfaces:
- `search` (anchor retrieval)
- `trace` (causal traversal)
- `execute` (single orchestration entrypoint)

Semantic mode behavior:
- `CORE_MEMORY_CANONICAL_SEMANTIC_MODE=required` (default) fails closed for query-based anchor lookup when semantic backend is unavailable.
- `CORE_MEMORY_CANONICAL_SEMANTIC_MODE=degraded_allowed` allows explicit degraded lexical fallback with markers.

Semantic backend deployment guidance:
- `faiss-*` local index is development/single-process oriented (single-writer).
- `qdrant` and `pgvector` are the recommended distributed-safe production backends.
- For multi-worker production deployments, avoid relying on local FAISS write paths.
- backend selection is explicit via `CORE_MEMORY_VECTOR_BACKEND` (`local-faiss|qdrant|pgvector|chromadb`).

See `docs/semantic_backend_modes.md` for backend mode details.

Hydration is explicit post-selection source recovery (turn/tools/adjacent), not a general retrieval mode.

Deep recall exists as a separate capability and is not the same thing as canonical hydration.

Retrieval is deterministic from indexed state.

---

## Repo Map

```text
core_memory/
├── persistence/
├── schema/
├── retrieval/
├── graph/
├── write_pipeline/
├── runtime/
├── association/
├── integrations/
├── policy/
└── cli.py
```

Other useful folders:

- `examples/` runnable examples
- `tests/` behavioral and regression coverage
- `docs/` architecture, integration guides, and contracts
- `plugins/` OpenClaw bridge assets
- `demo/` live demo app and assets

---

## Contributing

```bash
git clone https://github.com/JohnnyFiv3r/Core-Memory.git
cd Core-Memory
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e ".[dev]"
core-memory --help
python3 -c "import core_memory; print('core_memory import ok')"
pytest
```

Useful docs:

- [CONTRIBUTING.md](CONTRIBUTING.md)
- [docs/public_surface.md](docs/public_surface.md)
- [docs/index.md](docs/index.md)

---

## Inspiration

Inspired in part by Steve Yegge’s writing on beads and memory systems:
https://github.com/steveyegge/beads

---

## Maintainers

Core Memory is maintained by:

- John Inniger ([@JohnnyFiv3r](https://github.com/JohnnyFiv3r))
- Chris Dedow ([@chrisdedow](https://github.com/chrisdedow))

For bugs and feature requests, please open an issue. For anything else related to the project, feel free to reach out to the maintainers directly.

---

<p align="center">
 <a href="LICENSE">Apache-2.0 License</a> ·
 <a href="CODE_OF_CONDUCT.md">Code of Conduct</a> ·
 <a href="CHANGELOG.md">Changelog</a>
</p>
