agentkeeper-ai 1.1.0__tar.gz

agentkeeper_ai-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom — ThinkLanceAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentkeeper_ai-1.1.0/PKG-INFO

@@ -0,0 +1,328 @@
+Metadata-Version: 2.4
+Name: agentkeeper-ai
+Version: 1.1.0
+Summary: Cognitive continuity infrastructure for long-lived AI agents — cross-model state reconstruction, semantic recall, cognitive compression
+Author-email: Tom <hello@thinklanceai.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Thinklanceai/agentkeeper
+Project-URL: Repository, https://github.com/Thinklanceai/agentkeeper
+Project-URL: Issues, https://github.com/Thinklanceai/agentkeeper/issues
+Keywords: ai,agents,llm,memory,cognitive,continuity,openai,anthropic,claude,gemini,ollama
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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 :: Python Modules
+Classifier: Typing :: Typed
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: openai
+Requires-Dist: openai>=1.30.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30.0; extra == "anthropic"
+Provides-Extra: gemini
+Requires-Dist: google-generativeai>=0.8.0; extra == "gemini"
+Provides-Extra: dotenv
+Requires-Dist: python-dotenv>=1.0.0; extra == "dotenv"
+Provides-Extra: semantic
+Requires-Dist: sentence-transformers>=3.0.0; extra == "semantic"
+Provides-Extra: vec
+Requires-Dist: sqlite-vec>=0.1.6; extra == "vec"
+Provides-Extra: encrypted
+Requires-Dist: cryptography>=42.0.0; extra == "encrypted"
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=3.0.0; extra == "mcp"
+Provides-Extra: all
+Requires-Dist: openai>=1.30.0; extra == "all"
+Requires-Dist: anthropic>=0.30.0; extra == "all"
+Requires-Dist: google-generativeai>=0.8.0; extra == "all"
+Requires-Dist: python-dotenv>=1.0.0; extra == "all"
+Requires-Dist: sentence-transformers>=3.0.0; extra == "all"
+Requires-Dist: sqlite-vec>=0.1.6; extra == "all"
+Requires-Dist: cryptography>=42.0.0; extra == "all"
+Requires-Dist: fastmcp>=3.0.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: sqlite-vec>=0.1.6; extra == "dev"
+Requires-Dist: cryptography>=42.0.0; extra == "dev"
+Requires-Dist: fastmcp>=3.0.0; extra == "dev"
+Dynamic: license-file
+
+# AgentKeeper
+
+**Cognitive continuity infrastructure for long-lived AI agents.**
+
+AgentKeeper reconstructs persistent cognitive state across model switches, crashes, restarts, and constrained contexts.
+Built for agents that must survive longer than a single context window.
+
+[![PyPI version](https://img.shields.io/pypi/v/agentkeeper.svg)](https://pypi.org/project/agentkeeper/)
+[![Python versions](https://img.shields.io/pypi/pyversions/agentkeeper.svg)](https://pypi.org/project/agentkeeper/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/Thinklanceai/agentkeeper/actions/workflows/ci.yml/badge.svg)](https://github.com/Thinklanceai/agentkeeper/actions/workflows/ci.yml)
+[![Built by ThinkLanceAI](https://img.shields.io/badge/built%20by-ThinkLanceAI-4f8cff)](https://thinklanceai.com)
+
+---
+
+## Why AgentKeeper exists
+
+Agents don't fail because they forget facts.
+They fail because they lose **cognitive continuity** — their state, priorities, identity, and decision context drift the moment the underlying model changes, the context window fills, or the process restarts.
+
+AgentKeeper treats this as a systems problem, not a memory problem.
+
+It provides:
+
+- A **Cognitive Reconstruction Engine** that rebuilds an agent's state for the target model, every call.
+- A **memory hierarchy** (working / episodic / semantic / archival) with importance-aware retention.
+- **Semantic recall** based on embeddings — meaning, not keywords.
+- **Cognitive compression** — decay, consolidation, contradiction arbitration.
+- **Identity persistence** — principles and hard constraints that survive every form of compression.
+- **Cross-model translation** — XML for Claude, sections for GPT-4, narrative for Gemini, minimal for local models.
+
+Continuity, not just memory.
+
+## Install
+
+```bash
+pip install agentkeeper
+```
+
+Optional extras (only install what you need):
+
+```bash
+pip install 'agentkeeper[anthropic]'    # Claude
+pip install 'agentkeeper[openai]'       # GPT models + OpenAI embeddings
+pip install 'agentkeeper[gemini]'       # Google Gemini
+pip install 'agentkeeper[semantic]'     # Local embeddings (sentence-transformers)
+pip install 'agentkeeper[all]'          # everything
+```
+
+No external infrastructure required. Storage defaults to local SQLite. Vendor-agnostic by design.
+
+## 60-second tour
+
+```python
+import agentkeeper
+
+# 1. Create an agent and define its persistent identity
+agent = agentkeeper.create(agent_id="aria", provider="anthropic")
+agent.set_identity(
+    name="Aria",
+    role="EU insurance broker copilot",
+    principles=["never share PII without explicit consent"],
+    constraints=["EU data residency only"],
+)
+
+# 2. Teach it about the world
+agent.principle("always confirm budget changes in writing")
+agent.fact("client: Acme Corporation", importance=0.95)
+agent.event("contract signed", when="2026-05-15")
+agent.remember("favourite colour: blue")  # tier inferred automatically
+
+# 3. Ask — context is reconstructed for the target model
+response = agent.ask("What do we know about the Acme deal?")
+
+# 4. Switch providers — memory and identity survive
+agent.switch_provider("openai").save()
+response = agent.ask("Same question, different model.")
+```
+
+## Architecture
+
+```
+       ┌──────────────────────────────────────────────────────────────┐
+       │                  AgentKeeper Public API                       │
+       │  agent.remember() · agent.recall() · agent.ask()              │
+       │  agent.compress() · agent.set_identity() · agent.save()       │
+       └────────────────────────────┬──────────────────────────────────┘
+                                    │
+       ┌────────────────────────────▼──────────────────────────────────┐
+       │           Cognitive Reconstruction Engine (CRE)               │
+       │  Identity injection · importance ranking · semantic boost     │
+       │  Token budget · profile-driven rendering                      │
+       └─┬────────────┬────────────┬────────────┬─────────────────────┘
+         │            │            │            │
+   ┌─────▼─────┐ ┌───▼────────┐ ┌─▼─────────┐ ┌▼──────────────┐
+   │ Memory    │ │ Semantic   │ │ Cognitive │ │ Cross-Model    │
+   │ Hierarchy │ │ Recall     │ │ Compress  │ │ Translation    │
+   │           │ │            │ │           │ │                │
+   │ working   │ │ embeddings │ │ decay     │ │ XML / sections │
+   │ episodic  │ │ vector     │ │ consol.   │ │ narrative      │
+   │ semantic  │ │ index      │ │ contradic │ │ minimal        │
+   │ archival  │ │            │ │           │ │                │
+   └───────────┘ └────────────┘ └───────────┘ └────────────────┘
+                                    │
+                      ┌─────────────▼─────────────┐
+                      │   Storage (SQLite-first)  │
+                      │   Vendor-agnostic         │
+                      └───────────────────────────┘
+```
+
+Every layer is **interchangeable** and **opt-in**. The base CRE works with no embeddings, no compression, no profile customisation. Layers stack as you need them.
+
+## Cognitive continuity in five primitives
+
+### 1. Identity that never erodes
+
+```python
+agent.set_identity(
+    name="Aria",
+    role="EU broker copilot",
+    principles=["never share PII"],
+    constraints=["EU data residency only"],
+)
+```
+
+Identity is injected into every reconstructed context, regardless of token budget. It survives compression, model switches, and restarts. Principles are **protected** — never decayed, never consolidated, never flagged.
+
+### 2. Memory organised by tier
+
+```python
+agent.fact("budget: 50k EUR")                      # semantic (stable)
+agent.event("contract signed", when="2026-05-15")  # episodic (time-anchored)
+agent.principle("always confirm changes")          # protected, identity-level
+agent.remember("favourite colour: blue")           # tier inferred automatically
+```
+
+Tiers shape narration in reconstructed prompts and drive retention policy under compression.
+
+### 3. Semantic recall
+
+```python
+results = agent.recall("money allocated to the project", top_k=5)
+for fact, score in results:
+    print(f"{score:.2f}  {fact.content}")
+```
+
+Pluggable embedding providers: local `sentence-transformers` (default, free, no lock-in), OpenAI, or your own. Recall biases context reconstruction toward facts that actually matter for the current question.
+
+### 4. Cognitive compression
+
+```python
+report = agent.compress()
+# CompressionReport(
+#   decayed_facts=12,
+#   consolidation={'clusters_found': 3, 'facts_removed': 7, ...},
+#   contradictions={'pairs_found': 2, 'resolutions': 2},
+#   facts_before=120, facts_after=102,
+# )
+```
+
+Three independent passes:
+
+- **Decay** — exponential half-life on unused non-critical facts. Critical and protected facts are immortal.
+- **Consolidation** — embedding-based clustering merges near-duplicates. Optional LLM-backed synthesiser.
+- **Contradiction arbitration** — key-value divergence and polarity-opposition detection. Deterministic winner (critical > importance > recency). Loser is flagged, not deleted.
+
+### 5. Cross-model translation
+
+The same cognitive state, four formats:
+
+| Provider   | Format     | Why                                          |
+|------------|------------|-----------------------------------------------|
+| Anthropic  | XML        | Claude excels with structured `<agent_identity>` and `<memory>` blocks |
+| OpenAI     | Sections   | GPT family responds well to labelled sections (`AGENT IDENTITY`, `MEMORY`, `CURRENT TASK`) |
+| Gemini     | Narrative  | Long-context model — prefers prose framing |
+| Ollama     | Minimal    | Small/local models — aggressive compression, terse tokens |
+
+Custom providers? Register your own:
+
+```python
+from agentkeeper import CognitiveProfile, PromptFormat, register_profile
+
+register_profile(CognitiveProfile(
+    provider="my-llm",
+    format=PromptFormat.SECTIONS,
+    effective_context_tokens=10_000,
+))
+```
+
+## Async API
+
+```python
+import asyncio
+import agentkeeper
+
+async def main() -> None:
+    agent = agentkeeper.create_async(agent_id="aria", provider="anthropic")
+    agent.set_identity(name="Aria", role="copilot")
+    agent.fact("budget: 50k", importance=0.95)
+
+    # Parallel asks across providers
+    answers = await asyncio.gather(
+        agent.ask("status?", provider="anthropic"),
+        agent.ask("status?", provider="openai"),
+    )
+
+asyncio.run(main())
+```
+
+Sync and async agents share storage — you can save with one and load with the other.
+
+## Production-grade
+
+- **Type-safe**: `py.typed` marker shipped, mypy-strict friendly.
+- **Typed exceptions**: `AgentKeeperError` root, with subclasses for every failure mode (provider down, agent missing, retriable network errors).
+- **Structured logging**: namespaced under `agentkeeper.*`, opt-in.
+- **Retries**: built-in exponential backoff for transient provider errors via `with_retry` / `with_async_retry`.
+- **Tested**: 267 tests, CI on Python 3.10 / 3.11 / 3.12.
+
+## Configuration
+
+Environment variables (all optional):
+
+| Variable                          | Default                          | Purpose |
+|-----------------------------------|----------------------------------|---------|
+| `OPENAI_API_KEY`                  | —                                | Required for OpenAI provider |
+| `ANTHROPIC_API_KEY`               | —                                | Required for Anthropic provider |
+| `GEMINI_API_KEY`                  | —                                | Required for Gemini provider |
+| `OPENAI_MODEL`                    | `gpt-4-turbo`                    | OpenAI model name |
+| `ANTHROPIC_MODEL`                 | `claude-sonnet-4-5-20250929`     | Anthropic model name |
+| `OLLAMA_HOST`                     | `http://localhost:11434`         | Ollama server URL |
+| `AGENTKEEPER_DB`                  | `agentkeeper.db`                 | SQLite path |
+| `AGENTKEEPER_EMBEDDING_PROVIDER`  | auto (sentence-transformers > openai > mock) | Override embedding backend |
+
+## Roadmap (v1.x)
+
+- **v1.1** — Persistent vector index (`sqlite-vec`) so the recaller survives restarts without rebuild.
+- **v1.2** — Async LLM-backed synthesiser in compression.
+- **v1.3** — Pluggable storage backends (Postgres, encrypted).
+- **v1.4** — `AgentKeeper Cloud` (managed sync). *Stays optional; OSS remains feature-complete.*
+
+## Featured on
+
+AgentKeeper was vouched for in March 2026 by:
+
+- Shruti Codes ✓
+- Chidanand Tripathi ✓ ([80K-view thread](#))
+- Kayvon Jafarzadeh ✓
+- Leonard Rodman ✓
+- Martin Szerment ✓
+- Bespoke AI Solutions Inc ✓
+- @grok (xAI)
+
+If you've shipped agents that needed to survive across model changes, you understand why this matters. Thank you to everyone who saw the project early.
+
+## Contributing
+
+Issues, ideas, and PRs welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
+
+## Built by
+
+[**ThinkLanceAI**](https://thinklanceai.com) — cognitive infrastructure for AI systems.
+Need this in production with custom integrations? `hello@thinklanceai.com`.

agentkeeper_ai-1.1.0/README.md

@@ -0,0 +1,267 @@
+# AgentKeeper
+
+**Cognitive continuity infrastructure for long-lived AI agents.**
+
+AgentKeeper reconstructs persistent cognitive state across model switches, crashes, restarts, and constrained contexts.
+Built for agents that must survive longer than a single context window.
+
+[![PyPI version](https://img.shields.io/pypi/v/agentkeeper.svg)](https://pypi.org/project/agentkeeper/)
+[![Python versions](https://img.shields.io/pypi/pyversions/agentkeeper.svg)](https://pypi.org/project/agentkeeper/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/Thinklanceai/agentkeeper/actions/workflows/ci.yml/badge.svg)](https://github.com/Thinklanceai/agentkeeper/actions/workflows/ci.yml)
+[![Built by ThinkLanceAI](https://img.shields.io/badge/built%20by-ThinkLanceAI-4f8cff)](https://thinklanceai.com)
+
+---
+
+## Why AgentKeeper exists
+
+Agents don't fail because they forget facts.
+They fail because they lose **cognitive continuity** — their state, priorities, identity, and decision context drift the moment the underlying model changes, the context window fills, or the process restarts.
+
+AgentKeeper treats this as a systems problem, not a memory problem.
+
+It provides:
+
+- A **Cognitive Reconstruction Engine** that rebuilds an agent's state for the target model, every call.
+- A **memory hierarchy** (working / episodic / semantic / archival) with importance-aware retention.
+- **Semantic recall** based on embeddings — meaning, not keywords.
+- **Cognitive compression** — decay, consolidation, contradiction arbitration.
+- **Identity persistence** — principles and hard constraints that survive every form of compression.
+- **Cross-model translation** — XML for Claude, sections for GPT-4, narrative for Gemini, minimal for local models.
+
+Continuity, not just memory.
+
+## Install
+
+```bash
+pip install agentkeeper
+```
+
+Optional extras (only install what you need):
+
+```bash
+pip install 'agentkeeper[anthropic]'    # Claude
+pip install 'agentkeeper[openai]'       # GPT models + OpenAI embeddings
+pip install 'agentkeeper[gemini]'       # Google Gemini
+pip install 'agentkeeper[semantic]'     # Local embeddings (sentence-transformers)
+pip install 'agentkeeper[all]'          # everything
+```
+
+No external infrastructure required. Storage defaults to local SQLite. Vendor-agnostic by design.
+
+## 60-second tour
+
+```python
+import agentkeeper
+
+# 1. Create an agent and define its persistent identity
+agent = agentkeeper.create(agent_id="aria", provider="anthropic")
+agent.set_identity(
+    name="Aria",
+    role="EU insurance broker copilot",
+    principles=["never share PII without explicit consent"],
+    constraints=["EU data residency only"],
+)
+
+# 2. Teach it about the world
+agent.principle("always confirm budget changes in writing")
+agent.fact("client: Acme Corporation", importance=0.95)
+agent.event("contract signed", when="2026-05-15")
+agent.remember("favourite colour: blue")  # tier inferred automatically
+
+# 3. Ask — context is reconstructed for the target model
+response = agent.ask("What do we know about the Acme deal?")
+
+# 4. Switch providers — memory and identity survive
+agent.switch_provider("openai").save()
+response = agent.ask("Same question, different model.")
+```
+
+## Architecture
+
+```
+       ┌──────────────────────────────────────────────────────────────┐
+       │                  AgentKeeper Public API                       │
+       │  agent.remember() · agent.recall() · agent.ask()              │
+       │  agent.compress() · agent.set_identity() · agent.save()       │
+       └────────────────────────────┬──────────────────────────────────┘
+                                    │
+       ┌────────────────────────────▼──────────────────────────────────┐
+       │           Cognitive Reconstruction Engine (CRE)               │
+       │  Identity injection · importance ranking · semantic boost     │
+       │  Token budget · profile-driven rendering                      │
+       └─┬────────────┬────────────┬────────────┬─────────────────────┘
+         │            │            │            │
+   ┌─────▼─────┐ ┌───▼────────┐ ┌─▼─────────┐ ┌▼──────────────┐
+   │ Memory    │ │ Semantic   │ │ Cognitive │ │ Cross-Model    │
+   │ Hierarchy │ │ Recall     │ │ Compress  │ │ Translation    │
+   │           │ │            │ │           │ │                │
+   │ working   │ │ embeddings │ │ decay     │ │ XML / sections │
+   │ episodic  │ │ vector     │ │ consol.   │ │ narrative      │
+   │ semantic  │ │ index      │ │ contradic │ │ minimal        │
+   │ archival  │ │            │ │           │ │                │
+   └───────────┘ └────────────┘ └───────────┘ └────────────────┘
+                                    │
+                      ┌─────────────▼─────────────┐
+                      │   Storage (SQLite-first)  │
+                      │   Vendor-agnostic         │
+                      └───────────────────────────┘
+```
+
+Every layer is **interchangeable** and **opt-in**. The base CRE works with no embeddings, no compression, no profile customisation. Layers stack as you need them.
+
+## Cognitive continuity in five primitives
+
+### 1. Identity that never erodes
+
+```python
+agent.set_identity(
+    name="Aria",
+    role="EU broker copilot",
+    principles=["never share PII"],
+    constraints=["EU data residency only"],
+)
+```
+
+Identity is injected into every reconstructed context, regardless of token budget. It survives compression, model switches, and restarts. Principles are **protected** — never decayed, never consolidated, never flagged.
+
+### 2. Memory organised by tier
+
+```python
+agent.fact("budget: 50k EUR")                      # semantic (stable)
+agent.event("contract signed", when="2026-05-15")  # episodic (time-anchored)
+agent.principle("always confirm changes")          # protected, identity-level
+agent.remember("favourite colour: blue")           # tier inferred automatically
+```
+
+Tiers shape narration in reconstructed prompts and drive retention policy under compression.
+
+### 3. Semantic recall
+
+```python
+results = agent.recall("money allocated to the project", top_k=5)
+for fact, score in results:
+    print(f"{score:.2f}  {fact.content}")
+```
+
+Pluggable embedding providers: local `sentence-transformers` (default, free, no lock-in), OpenAI, or your own. Recall biases context reconstruction toward facts that actually matter for the current question.
+
+### 4. Cognitive compression
+
+```python
+report = agent.compress()
+# CompressionReport(
+#   decayed_facts=12,
+#   consolidation={'clusters_found': 3, 'facts_removed': 7, ...},
+#   contradictions={'pairs_found': 2, 'resolutions': 2},
+#   facts_before=120, facts_after=102,
+# )
+```
+
+Three independent passes:
+
+- **Decay** — exponential half-life on unused non-critical facts. Critical and protected facts are immortal.
+- **Consolidation** — embedding-based clustering merges near-duplicates. Optional LLM-backed synthesiser.
+- **Contradiction arbitration** — key-value divergence and polarity-opposition detection. Deterministic winner (critical > importance > recency). Loser is flagged, not deleted.
+
+### 5. Cross-model translation
+
+The same cognitive state, four formats:
+
+| Provider   | Format     | Why                                          |
+|------------|------------|-----------------------------------------------|
+| Anthropic  | XML        | Claude excels with structured `<agent_identity>` and `<memory>` blocks |
+| OpenAI     | Sections   | GPT family responds well to labelled sections (`AGENT IDENTITY`, `MEMORY`, `CURRENT TASK`) |
+| Gemini     | Narrative  | Long-context model — prefers prose framing |
+| Ollama     | Minimal    | Small/local models — aggressive compression, terse tokens |
+
+Custom providers? Register your own:
+
+```python
+from agentkeeper import CognitiveProfile, PromptFormat, register_profile
+
+register_profile(CognitiveProfile(
+    provider="my-llm",
+    format=PromptFormat.SECTIONS,
+    effective_context_tokens=10_000,
+))
+```
+
+## Async API
+
+```python
+import asyncio
+import agentkeeper
+
+async def main() -> None:
+    agent = agentkeeper.create_async(agent_id="aria", provider="anthropic")
+    agent.set_identity(name="Aria", role="copilot")
+    agent.fact("budget: 50k", importance=0.95)
+
+    # Parallel asks across providers
+    answers = await asyncio.gather(
+        agent.ask("status?", provider="anthropic"),
+        agent.ask("status?", provider="openai"),
+    )
+
+asyncio.run(main())
+```
+
+Sync and async agents share storage — you can save with one and load with the other.
+
+## Production-grade
+
+- **Type-safe**: `py.typed` marker shipped, mypy-strict friendly.
+- **Typed exceptions**: `AgentKeeperError` root, with subclasses for every failure mode (provider down, agent missing, retriable network errors).
+- **Structured logging**: namespaced under `agentkeeper.*`, opt-in.
+- **Retries**: built-in exponential backoff for transient provider errors via `with_retry` / `with_async_retry`.
+- **Tested**: 267 tests, CI on Python 3.10 / 3.11 / 3.12.
+
+## Configuration
+
+Environment variables (all optional):
+
+| Variable                          | Default                          | Purpose |
+|-----------------------------------|----------------------------------|---------|
+| `OPENAI_API_KEY`                  | —                                | Required for OpenAI provider |
+| `ANTHROPIC_API_KEY`               | —                                | Required for Anthropic provider |
+| `GEMINI_API_KEY`                  | —                                | Required for Gemini provider |
+| `OPENAI_MODEL`                    | `gpt-4-turbo`                    | OpenAI model name |
+| `ANTHROPIC_MODEL`                 | `claude-sonnet-4-5-20250929`     | Anthropic model name |
+| `OLLAMA_HOST`                     | `http://localhost:11434`         | Ollama server URL |
+| `AGENTKEEPER_DB`                  | `agentkeeper.db`                 | SQLite path |
+| `AGENTKEEPER_EMBEDDING_PROVIDER`  | auto (sentence-transformers > openai > mock) | Override embedding backend |
+
+## Roadmap (v1.x)
+
+- **v1.1** — Persistent vector index (`sqlite-vec`) so the recaller survives restarts without rebuild.
+- **v1.2** — Async LLM-backed synthesiser in compression.
+- **v1.3** — Pluggable storage backends (Postgres, encrypted).
+- **v1.4** — `AgentKeeper Cloud` (managed sync). *Stays optional; OSS remains feature-complete.*
+
+## Featured on
+
+AgentKeeper was vouched for in March 2026 by:
+
+- Shruti Codes ✓
+- Chidanand Tripathi ✓ ([80K-view thread](#))
+- Kayvon Jafarzadeh ✓
+- Leonard Rodman ✓
+- Martin Szerment ✓
+- Bespoke AI Solutions Inc ✓
+- @grok (xAI)
+
+If you've shipped agents that needed to survive across model changes, you understand why this matters. Thank you to everyone who saw the project early.
+
+## Contributing
+
+Issues, ideas, and PRs welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
+
+## Built by
+
+[**ThinkLanceAI**](https://thinklanceai.com) — cognitive infrastructure for AI systems.
+Need this in production with custom integrations? `hello@thinklanceai.com`.