agentdatabase 0.3.0__tar.gz → 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. agentdatabase-0.4.0/PKG-INFO +208 -0
  2. agentdatabase-0.4.0/README.md +166 -0
  3. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/pyproject.toml +1 -1
  4. agentdatabase-0.4.0/src/agentdatabase.egg-info/PKG-INFO +208 -0
  5. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdatabase.egg-info/SOURCES.txt +1 -0
  6. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/adapters/__init__.py +2 -2
  7. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/adapters/capabilities.py +4 -2
  8. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/core/models.py +1 -0
  9. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/core/store.py +9 -3
  10. agentdatabase-0.4.0/src/agentdb/ingest.py +225 -0
  11. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/interface/client.py +226 -4
  12. agentdatabase-0.3.0/PKG-INFO +0 -920
  13. agentdatabase-0.3.0/README.md +0 -878
  14. agentdatabase-0.3.0/src/agentdatabase.egg-info/PKG-INFO +0 -920
  15. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/LICENSE +0 -0
  16. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/setup.cfg +0 -0
  17. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdatabase.egg-info/dependency_links.txt +0 -0
  18. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdatabase.egg-info/entry_points.txt +0 -0
  19. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdatabase.egg-info/requires.txt +0 -0
  20. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdatabase.egg-info/top_level.txt +0 -0
  21. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/__init__.py +0 -0
  22. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/adapters/claude_agent_sdk.py +0 -0
  23. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/adapters/hermes.py +0 -0
  24. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/adapters/middleware.py +0 -0
  25. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/backend.py +0 -0
  26. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/core/__init__.py +0 -0
  27. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/core/directory_tracking.py +0 -0
  28. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/core/file_integrity.py +0 -0
  29. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/core/profiles.py +0 -0
  30. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/core/system.py +0 -0
  31. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/embeddings/__init__.py +0 -0
  32. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/embeddings/provider.py +0 -0
  33. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/embeddings/store.py +0 -0
  34. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/embeddings/text.py +0 -0
  35. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/gateway/__init__.py +0 -0
  36. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/gateway/adapter.py +0 -0
  37. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/governance/__init__.py +0 -0
  38. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/governance/conflict_detector.py +0 -0
  39. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/governance/lifecycle_manager.py +0 -0
  40. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/governance/permission_router.py +0 -0
  41. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/interface/__init__.py +0 -0
  42. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/interface/mcp_server.py +0 -0
  43. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/notifications/__init__.py +0 -0
  44. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/notifications/channels.py +0 -0
  45. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/notifications/dispatcher.py +0 -0
  46. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/providers/__init__.py +0 -0
  47. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/providers/anthropic.py +0 -0
  48. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/retrieval/__init__.py +0 -0
  49. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/retrieval/algorithm.py +0 -0
  50. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/skills/__init__.py +0 -0
  51. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/skills/evolution/__init__.py +0 -0
  52. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/skills/evolution/manager.py +0 -0
  53. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/skills/evolution/skillopt_adapter.py +0 -0
  54. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/skills/evolution/wikiskill_adapter.py +0 -0
  55. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/skills/skill_store.py +0 -0
  56. {agentdatabase-0.3.0 → agentdatabase-0.4.0}/src/agentdb/testing.py +0 -0
@@ -0,0 +1,208 @@
1
+ Metadata-Version: 2.4
2
+ Name: agentdatabase
3
+ Version: 0.4.0
4
+ Summary: Governed memory layer for AI agents
5
+ Author-email: DatoSurf <team@datosurf.com>
6
+ License: AGPL-3.0
7
+ Project-URL: Homepage, https://github.com/datosurf-dev/agentdb
8
+ Project-URL: Repository, https://github.com/datosurf-dev/agentdb
9
+ Project-URL: Bug Tracker, https://github.com/datosurf-dev/agentdb/issues
10
+ Keywords: ai,agents,memory,llm,rag,context
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: License :: OSI Approved :: GNU Affero General Public License v3
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
18
+ Classifier: Intended Audience :: Developers
19
+ Requires-Python: >=3.11
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: pyyaml>=6.0
23
+ Provides-Extra: dev
24
+ Requires-Dist: pytest>=8.0; extra == "dev"
25
+ Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
26
+ Provides-Extra: mcp
27
+ Requires-Dist: mcp<2.0,>=1.0; extra == "mcp"
28
+ Provides-Extra: local-embed
29
+ Requires-Dist: sentence-transformers<4.0,>=2.7; extra == "local-embed"
30
+ Provides-Extra: wikiskill
31
+ Requires-Dist: wikiskill>=0.1.0; extra == "wikiskill"
32
+ Provides-Extra: skillopt
33
+ Requires-Dist: skillopt>=0.1.0; extra == "skillopt"
34
+ Provides-Extra: evolution
35
+ Requires-Dist: wikiskill>=0.1.0; extra == "evolution"
36
+ Requires-Dist: skillopt>=0.1.0; extra == "evolution"
37
+ Provides-Extra: notifications
38
+ Requires-Dist: slack-sdk>=3.0; extra == "notifications"
39
+ Provides-Extra: providers
40
+ Requires-Dist: anthropic>=0.20; extra == "providers"
41
+ Dynamic: license-file
42
+
43
+ # AgentDB
44
+
45
+ **A governed memory layer for Python agents.** AgentDB stores agent memories with provenance, applies optional write policies, ranks retrieved records, tracks conflicts, and provides adapters for feeding governed context into agent runtimes.
46
+
47
+ AgentDB is a local Python library backed by SQLite. It complements an agent runtime; it is not a hosted service, a vector database, or a replacement for the model provider.
48
+
49
+ ## Current implementation
50
+
51
+ The package currently provides:
52
+
53
+ - **Memory API:** `write`, `read`, `delete`, `retrieve`, and entity-based retrieval, with audit events for writes, deletes, and retrievals.
54
+ - **Provenance:** records are marked `human_approved`, `agent_inferred`, or `provider_ingested`; provider data is not promoted to human-approved data.
55
+ - **Optional write authorization:** a YAML `PermissionRouter` can authorize writes and deletes. It is only active when `permissions_path` is supplied.
56
+ - **Ranked retrieval:** provenance, recency, confidence, retrieval-frequency approximation, optional workspace overlap, and optional embedding similarity. Retrieval supports record limits and token budgets.
57
+ - **Conflict and governance signals:** write-time conflicts, external-context overlap checks, skill-review signals, a conflict queue, and a live in-process gateway dispatcher.
58
+ - **Skills:** separately stored, versioned records with health/staleness tracking, plus proposal and approval workflows. Core `retrieve()` does not return skills; some adapters can inject skill context.
59
+ - **Lifecycle:** outcomes and reinforcement, manual lifecycle sweeps, TTL/staleness archival, and memory consolidation. On conversation start, automatic consolidation requires at least seven days and ten sessions since the previous run.
60
+ - **Runtime integration:** a generic `AgentDBBackend`, model-agnostic middleware, a Claude runtime wrapper, and a Hermes `MemoryProvider` adapter.
61
+ - **Optional integrations:** stdio MCP server, Anthropic message ingestor, email/Slack notifications, and WikiSkill/SkillOpt skill-evolution bridges.
62
+
63
+ The current storage implementation is embedded SQLite. There is no Postgres/cloud backend or HTTP MCP transport. The gateway dispatcher is in-memory; the audit log is stored separately in SQLite.
64
+
65
+ ## Install
66
+
67
+ For development:
68
+
69
+ ```bash
70
+ python3 -m venv .venv
71
+ source .venv/bin/activate
72
+ python -m pip install -e '.[dev,mcp]'
73
+ ```
74
+
75
+ Optional extras (the distribution name is `agentdatabase`):
76
+
77
+ ```bash
78
+ python -m pip install 'agentdatabase[local-embed]' # local sentence-transformer embeddings
79
+ python -m pip install 'agentdatabase[mcp]' # stdio MCP server
80
+ python -m pip install 'agentdatabase[providers]' # Anthropic provider client
81
+ python -m pip install 'agentdatabase[notifications]' # Slack notifications
82
+ python -m pip install 'agentdatabase[evolution]' # WikiSkill and SkillOpt bridges
83
+ ```
84
+
85
+ Email notifications use the Python standard library. The `notifications` extra is needed for Slack.
86
+
87
+ ## Quick start
88
+
89
+ Pass a `memory_dir` or `path` when constructing the client:
90
+
91
+ ```python
92
+ from agentdb import AgentDB
93
+
94
+ # Creates config/, database/, and other workspace directories as needed.
95
+ db = AgentDB(memory_dir="./agentdb-memory")
96
+
97
+ record = db.write(
98
+ key="memory/working/response_style",
99
+ value="Prefer concise bullet points.",
100
+ origin="agent_inferred",
101
+ agent_id="assistant",
102
+ )
103
+
104
+ result = db.retrieve("How should I format the response?", agent_id="assistant")
105
+ print([record.value for record in result.records])
106
+ ```
107
+
108
+ The default workspace configuration is written to `config/memory.yaml`. Set `AGENTDB_MEMORY_DIR` or `AGENTDB_HOME` to choose a workspace through the environment.
109
+
110
+ ## Permissions and trust
111
+
112
+ Provide `permissions_path` to enable write/delete checks:
113
+
114
+ ```python
115
+ db = AgentDB(
116
+ memory_dir="./agentdb-memory",
117
+ permissions_path="./permissions.yaml",
118
+ )
119
+ ```
120
+
121
+ Example policy:
122
+
123
+ ```yaml
124
+ default_policy: deny
125
+ human_zone_prefixes:
126
+ - "skills/"
127
+ agents:
128
+ assistant:
129
+ can_write:
130
+ - "memory/working/"
131
+ cannot_write:
132
+ - "skills/"
133
+ ```
134
+
135
+ Important current limits:
136
+
137
+ - Without `permissions_path`, the permission router is not active.
138
+ - `read()` and `retrieve()` do not enforce `can_read`; do not treat that field as a read-access boundary.
139
+ - Agent-scoped retrieval is enabled for agents configured under `profile.agents` in `memory.yaml`; otherwise retrieval is not filtered by `agent_id`.
140
+ - The router governs calls through the client API; direct access to internal storage is outside that control path.
141
+ - The no-argument `AgentDB()` constructor currently selects SQLite's `:memory:` path, but initialization fails because the store opens separate short-lived connections. Use `memory_dir=` or `path=` instead.
142
+
143
+ ## Configuration and embeddings
144
+
145
+ `memory.yaml` uses a named profile with optional overrides. Built-in profiles are `budget_optimized`, `full_storage`, and `research`:
146
+
147
+ ```yaml
148
+ profile:
149
+ name: budget_optimized
150
+ agents:
151
+ assistant:
152
+ retrieval:
153
+ retrieve_limit: 10
154
+
155
+ # Embeddings are off unless enabled or supplied through the constructor.
156
+ embeddings:
157
+ enabled: true
158
+ # model: sentence-transformers/all-MiniLM-L6-v2
159
+ ```
160
+
161
+ Embeddings can also be enabled with `AgentDB(local_embed=True)` or a custom `embed_fn(text) -> list[float]`. They enable semantic ranking and embedding-based conflict checks. Local embeddings require the `local-embed` extra; embedding support is disabled by default.
162
+
163
+ ## Main API surfaces
164
+
165
+ - `AgentDB`: memory writes/reads/retrieval, `consolidate()`, `checkpoint()`, `write_compaction_summary()`, `record_outcome()`, `config`, and `config_for(agent_id)`.
166
+ - `db.lifecycle`: lifecycle sweeps, reinforcement, and outcome recording. Sweeps are not run by a background scheduler.
167
+ - `db.gateway`: in-process event subscriptions/dispatch, conflict queue, and skill proposals.
168
+ - `db.skills_api`: create, version, retrieve, archive, and inspect skill warnings.
169
+ - `db.system.agentdb_stats()`: corpus and outcome statistics.
170
+ - `db.audit_log.replay()`: replay persisted audit entries.
171
+ - `AgentDBBackend` (`from agentdb.backend import AgentDBBackend`): key/value `read`, `write`, `delete`, `list`, `grep`, and `glob` for a selected agent and trust zone.
172
+
173
+ Retrieval returns `RetrievalResult` with records, conflicts, authority override instructions, a token estimate, and a truncation flag. `retrieve_by_entities()` supports action-oriented lookups. Semantic matching requires embeddings; without them, retrieval uses the non-semantic signals and existing text/entity matching.
174
+
175
+ ## Runtime integrations
176
+
177
+ ### Model-agnostic middleware
178
+
179
+ `AgentDBMiddleware` (`from agentdb.adapters import AgentDBMiddleware`) provides `prepare_turn` / `finalize_turn` and `run_turn`, plus async variants. The async preparation path can inject skills, workspace information, and recent work context according to `RunnerCapabilities`; the synchronous path prepares memory context.
180
+
181
+ ### Claude
182
+
183
+ `AgentDBClaudeRuntime` supports synchronous model clients and an async Claude SDK client factory. `AgentDBClaudeMiddleware` remains available as a backward-compatible import. The adapter exposes a `PreToolUse` hook map through `get_sdk_hooks()`; the integrating application is responsible for registering that hook with its SDK/runtime.
184
+
185
+ ### Hermes
186
+
187
+ `AgentDBHermesProvider` implements Hermes's `MemoryProvider` interface. It supplies retrieval, turn persistence, skills context, and lifecycle hooks. Governance applies to AgentDB records; a post-write Hermes hook cannot veto a write already made to Hermes-native storage.
188
+
189
+ ### Other frameworks
190
+
191
+ No dedicated deepagents, LangGraph, CrewAI, OpenAI Agents, Google ADK, or AutoGen adapter is included. Use `AgentDBBackend` where the framework supports a pluggable key/value backend, or integrate `AgentDBMiddleware` at the runtime's own control points.
192
+
193
+ See [`docs/integrations/README.md`](docs/integrations/README.md) for integration guides.
194
+
195
+ ## Optional services
196
+
197
+ - **MCP:** `agentdb-mcp` starts a stdio server with `memory_write`, `memory_retrieve`, `conflict_queue`, and `memory_stats`. Set `AGENTDB_MEMORY_DIR` to select its workspace. HTTP transport is not implemented.
198
+ - **Anthropic ingestion:** `AnthropicProvider(db, client).sync(agent_id, limit=50)` ingests text message blocks as `provider_ingested` records.
199
+ - **Notifications:** configure email or Slack channels in `memory.yaml`; dispatch is live and in-process, not a durable queue.
200
+ - **Skill evolution:** `src/agentdb/skills/evolution/` contains WikiSkill and SkillOpt adapters for applying proposed or accepted skill versions.
201
+
202
+ ## Tests
203
+
204
+ ```bash
205
+ python -m pytest -q
206
+ ```
207
+
208
+ See [`docs/context/testing-strategy.md`](docs/context/testing-strategy.md) for focused test commands and [`docs/context/architecture-principles.md`](docs/context/architecture-principles.md) for the design constraints. The repository uses a `src/` layout and package imports such as `from agentdb import AgentDB`.
@@ -0,0 +1,166 @@
1
+ # AgentDB
2
+
3
+ **A governed memory layer for Python agents.** AgentDB stores agent memories with provenance, applies optional write policies, ranks retrieved records, tracks conflicts, and provides adapters for feeding governed context into agent runtimes.
4
+
5
+ AgentDB is a local Python library backed by SQLite. It complements an agent runtime; it is not a hosted service, a vector database, or a replacement for the model provider.
6
+
7
+ ## Current implementation
8
+
9
+ The package currently provides:
10
+
11
+ - **Memory API:** `write`, `read`, `delete`, `retrieve`, and entity-based retrieval, with audit events for writes, deletes, and retrievals.
12
+ - **Provenance:** records are marked `human_approved`, `agent_inferred`, or `provider_ingested`; provider data is not promoted to human-approved data.
13
+ - **Optional write authorization:** a YAML `PermissionRouter` can authorize writes and deletes. It is only active when `permissions_path` is supplied.
14
+ - **Ranked retrieval:** provenance, recency, confidence, retrieval-frequency approximation, optional workspace overlap, and optional embedding similarity. Retrieval supports record limits and token budgets.
15
+ - **Conflict and governance signals:** write-time conflicts, external-context overlap checks, skill-review signals, a conflict queue, and a live in-process gateway dispatcher.
16
+ - **Skills:** separately stored, versioned records with health/staleness tracking, plus proposal and approval workflows. Core `retrieve()` does not return skills; some adapters can inject skill context.
17
+ - **Lifecycle:** outcomes and reinforcement, manual lifecycle sweeps, TTL/staleness archival, and memory consolidation. On conversation start, automatic consolidation requires at least seven days and ten sessions since the previous run.
18
+ - **Runtime integration:** a generic `AgentDBBackend`, model-agnostic middleware, a Claude runtime wrapper, and a Hermes `MemoryProvider` adapter.
19
+ - **Optional integrations:** stdio MCP server, Anthropic message ingestor, email/Slack notifications, and WikiSkill/SkillOpt skill-evolution bridges.
20
+
21
+ The current storage implementation is embedded SQLite. There is no Postgres/cloud backend or HTTP MCP transport. The gateway dispatcher is in-memory; the audit log is stored separately in SQLite.
22
+
23
+ ## Install
24
+
25
+ For development:
26
+
27
+ ```bash
28
+ python3 -m venv .venv
29
+ source .venv/bin/activate
30
+ python -m pip install -e '.[dev,mcp]'
31
+ ```
32
+
33
+ Optional extras (the distribution name is `agentdatabase`):
34
+
35
+ ```bash
36
+ python -m pip install 'agentdatabase[local-embed]' # local sentence-transformer embeddings
37
+ python -m pip install 'agentdatabase[mcp]' # stdio MCP server
38
+ python -m pip install 'agentdatabase[providers]' # Anthropic provider client
39
+ python -m pip install 'agentdatabase[notifications]' # Slack notifications
40
+ python -m pip install 'agentdatabase[evolution]' # WikiSkill and SkillOpt bridges
41
+ ```
42
+
43
+ Email notifications use the Python standard library. The `notifications` extra is needed for Slack.
44
+
45
+ ## Quick start
46
+
47
+ Pass a `memory_dir` or `path` when constructing the client:
48
+
49
+ ```python
50
+ from agentdb import AgentDB
51
+
52
+ # Creates config/, database/, and other workspace directories as needed.
53
+ db = AgentDB(memory_dir="./agentdb-memory")
54
+
55
+ record = db.write(
56
+ key="memory/working/response_style",
57
+ value="Prefer concise bullet points.",
58
+ origin="agent_inferred",
59
+ agent_id="assistant",
60
+ )
61
+
62
+ result = db.retrieve("How should I format the response?", agent_id="assistant")
63
+ print([record.value for record in result.records])
64
+ ```
65
+
66
+ The default workspace configuration is written to `config/memory.yaml`. Set `AGENTDB_MEMORY_DIR` or `AGENTDB_HOME` to choose a workspace through the environment.
67
+
68
+ ## Permissions and trust
69
+
70
+ Provide `permissions_path` to enable write/delete checks:
71
+
72
+ ```python
73
+ db = AgentDB(
74
+ memory_dir="./agentdb-memory",
75
+ permissions_path="./permissions.yaml",
76
+ )
77
+ ```
78
+
79
+ Example policy:
80
+
81
+ ```yaml
82
+ default_policy: deny
83
+ human_zone_prefixes:
84
+ - "skills/"
85
+ agents:
86
+ assistant:
87
+ can_write:
88
+ - "memory/working/"
89
+ cannot_write:
90
+ - "skills/"
91
+ ```
92
+
93
+ Important current limits:
94
+
95
+ - Without `permissions_path`, the permission router is not active.
96
+ - `read()` and `retrieve()` do not enforce `can_read`; do not treat that field as a read-access boundary.
97
+ - Agent-scoped retrieval is enabled for agents configured under `profile.agents` in `memory.yaml`; otherwise retrieval is not filtered by `agent_id`.
98
+ - The router governs calls through the client API; direct access to internal storage is outside that control path.
99
+ - The no-argument `AgentDB()` constructor currently selects SQLite's `:memory:` path, but initialization fails because the store opens separate short-lived connections. Use `memory_dir=` or `path=` instead.
100
+
101
+ ## Configuration and embeddings
102
+
103
+ `memory.yaml` uses a named profile with optional overrides. Built-in profiles are `budget_optimized`, `full_storage`, and `research`:
104
+
105
+ ```yaml
106
+ profile:
107
+ name: budget_optimized
108
+ agents:
109
+ assistant:
110
+ retrieval:
111
+ retrieve_limit: 10
112
+
113
+ # Embeddings are off unless enabled or supplied through the constructor.
114
+ embeddings:
115
+ enabled: true
116
+ # model: sentence-transformers/all-MiniLM-L6-v2
117
+ ```
118
+
119
+ Embeddings can also be enabled with `AgentDB(local_embed=True)` or a custom `embed_fn(text) -> list[float]`. They enable semantic ranking and embedding-based conflict checks. Local embeddings require the `local-embed` extra; embedding support is disabled by default.
120
+
121
+ ## Main API surfaces
122
+
123
+ - `AgentDB`: memory writes/reads/retrieval, `consolidate()`, `checkpoint()`, `write_compaction_summary()`, `record_outcome()`, `config`, and `config_for(agent_id)`.
124
+ - `db.lifecycle`: lifecycle sweeps, reinforcement, and outcome recording. Sweeps are not run by a background scheduler.
125
+ - `db.gateway`: in-process event subscriptions/dispatch, conflict queue, and skill proposals.
126
+ - `db.skills_api`: create, version, retrieve, archive, and inspect skill warnings.
127
+ - `db.system.agentdb_stats()`: corpus and outcome statistics.
128
+ - `db.audit_log.replay()`: replay persisted audit entries.
129
+ - `AgentDBBackend` (`from agentdb.backend import AgentDBBackend`): key/value `read`, `write`, `delete`, `list`, `grep`, and `glob` for a selected agent and trust zone.
130
+
131
+ Retrieval returns `RetrievalResult` with records, conflicts, authority override instructions, a token estimate, and a truncation flag. `retrieve_by_entities()` supports action-oriented lookups. Semantic matching requires embeddings; without them, retrieval uses the non-semantic signals and existing text/entity matching.
132
+
133
+ ## Runtime integrations
134
+
135
+ ### Model-agnostic middleware
136
+
137
+ `AgentDBMiddleware` (`from agentdb.adapters import AgentDBMiddleware`) provides `prepare_turn` / `finalize_turn` and `run_turn`, plus async variants. The async preparation path can inject skills, workspace information, and recent work context according to `RunnerCapabilities`; the synchronous path prepares memory context.
138
+
139
+ ### Claude
140
+
141
+ `AgentDBClaudeRuntime` supports synchronous model clients and an async Claude SDK client factory. `AgentDBClaudeMiddleware` remains available as a backward-compatible import. The adapter exposes a `PreToolUse` hook map through `get_sdk_hooks()`; the integrating application is responsible for registering that hook with its SDK/runtime.
142
+
143
+ ### Hermes
144
+
145
+ `AgentDBHermesProvider` implements Hermes's `MemoryProvider` interface. It supplies retrieval, turn persistence, skills context, and lifecycle hooks. Governance applies to AgentDB records; a post-write Hermes hook cannot veto a write already made to Hermes-native storage.
146
+
147
+ ### Other frameworks
148
+
149
+ No dedicated deepagents, LangGraph, CrewAI, OpenAI Agents, Google ADK, or AutoGen adapter is included. Use `AgentDBBackend` where the framework supports a pluggable key/value backend, or integrate `AgentDBMiddleware` at the runtime's own control points.
150
+
151
+ See [`docs/integrations/README.md`](docs/integrations/README.md) for integration guides.
152
+
153
+ ## Optional services
154
+
155
+ - **MCP:** `agentdb-mcp` starts a stdio server with `memory_write`, `memory_retrieve`, `conflict_queue`, and `memory_stats`. Set `AGENTDB_MEMORY_DIR` to select its workspace. HTTP transport is not implemented.
156
+ - **Anthropic ingestion:** `AnthropicProvider(db, client).sync(agent_id, limit=50)` ingests text message blocks as `provider_ingested` records.
157
+ - **Notifications:** configure email or Slack channels in `memory.yaml`; dispatch is live and in-process, not a durable queue.
158
+ - **Skill evolution:** `src/agentdb/skills/evolution/` contains WikiSkill and SkillOpt adapters for applying proposed or accepted skill versions.
159
+
160
+ ## Tests
161
+
162
+ ```bash
163
+ python -m pytest -q
164
+ ```
165
+
166
+ See [`docs/context/testing-strategy.md`](docs/context/testing-strategy.md) for focused test commands and [`docs/context/architecture-principles.md`](docs/context/architecture-principles.md) for the design constraints. The repository uses a `src/` layout and package imports such as `from agentdb import AgentDB`.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "agentdatabase"
7
- version = "0.3.0"
7
+ version = "0.4.0"
8
8
  description = "Governed memory layer for AI agents"
9
9
  readme = "README.md"
10
10
  license = {text = "AGPL-3.0"}
@@ -0,0 +1,208 @@
1
+ Metadata-Version: 2.4
2
+ Name: agentdatabase
3
+ Version: 0.4.0
4
+ Summary: Governed memory layer for AI agents
5
+ Author-email: DatoSurf <team@datosurf.com>
6
+ License: AGPL-3.0
7
+ Project-URL: Homepage, https://github.com/datosurf-dev/agentdb
8
+ Project-URL: Repository, https://github.com/datosurf-dev/agentdb
9
+ Project-URL: Bug Tracker, https://github.com/datosurf-dev/agentdb/issues
10
+ Keywords: ai,agents,memory,llm,rag,context
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: License :: OSI Approved :: GNU Affero General Public License v3
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
18
+ Classifier: Intended Audience :: Developers
19
+ Requires-Python: >=3.11
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: pyyaml>=6.0
23
+ Provides-Extra: dev
24
+ Requires-Dist: pytest>=8.0; extra == "dev"
25
+ Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
26
+ Provides-Extra: mcp
27
+ Requires-Dist: mcp<2.0,>=1.0; extra == "mcp"
28
+ Provides-Extra: local-embed
29
+ Requires-Dist: sentence-transformers<4.0,>=2.7; extra == "local-embed"
30
+ Provides-Extra: wikiskill
31
+ Requires-Dist: wikiskill>=0.1.0; extra == "wikiskill"
32
+ Provides-Extra: skillopt
33
+ Requires-Dist: skillopt>=0.1.0; extra == "skillopt"
34
+ Provides-Extra: evolution
35
+ Requires-Dist: wikiskill>=0.1.0; extra == "evolution"
36
+ Requires-Dist: skillopt>=0.1.0; extra == "evolution"
37
+ Provides-Extra: notifications
38
+ Requires-Dist: slack-sdk>=3.0; extra == "notifications"
39
+ Provides-Extra: providers
40
+ Requires-Dist: anthropic>=0.20; extra == "providers"
41
+ Dynamic: license-file
42
+
43
+ # AgentDB
44
+
45
+ **A governed memory layer for Python agents.** AgentDB stores agent memories with provenance, applies optional write policies, ranks retrieved records, tracks conflicts, and provides adapters for feeding governed context into agent runtimes.
46
+
47
+ AgentDB is a local Python library backed by SQLite. It complements an agent runtime; it is not a hosted service, a vector database, or a replacement for the model provider.
48
+
49
+ ## Current implementation
50
+
51
+ The package currently provides:
52
+
53
+ - **Memory API:** `write`, `read`, `delete`, `retrieve`, and entity-based retrieval, with audit events for writes, deletes, and retrievals.
54
+ - **Provenance:** records are marked `human_approved`, `agent_inferred`, or `provider_ingested`; provider data is not promoted to human-approved data.
55
+ - **Optional write authorization:** a YAML `PermissionRouter` can authorize writes and deletes. It is only active when `permissions_path` is supplied.
56
+ - **Ranked retrieval:** provenance, recency, confidence, retrieval-frequency approximation, optional workspace overlap, and optional embedding similarity. Retrieval supports record limits and token budgets.
57
+ - **Conflict and governance signals:** write-time conflicts, external-context overlap checks, skill-review signals, a conflict queue, and a live in-process gateway dispatcher.
58
+ - **Skills:** separately stored, versioned records with health/staleness tracking, plus proposal and approval workflows. Core `retrieve()` does not return skills; some adapters can inject skill context.
59
+ - **Lifecycle:** outcomes and reinforcement, manual lifecycle sweeps, TTL/staleness archival, and memory consolidation. On conversation start, automatic consolidation requires at least seven days and ten sessions since the previous run.
60
+ - **Runtime integration:** a generic `AgentDBBackend`, model-agnostic middleware, a Claude runtime wrapper, and a Hermes `MemoryProvider` adapter.
61
+ - **Optional integrations:** stdio MCP server, Anthropic message ingestor, email/Slack notifications, and WikiSkill/SkillOpt skill-evolution bridges.
62
+
63
+ The current storage implementation is embedded SQLite. There is no Postgres/cloud backend or HTTP MCP transport. The gateway dispatcher is in-memory; the audit log is stored separately in SQLite.
64
+
65
+ ## Install
66
+
67
+ For development:
68
+
69
+ ```bash
70
+ python3 -m venv .venv
71
+ source .venv/bin/activate
72
+ python -m pip install -e '.[dev,mcp]'
73
+ ```
74
+
75
+ Optional extras (the distribution name is `agentdatabase`):
76
+
77
+ ```bash
78
+ python -m pip install 'agentdatabase[local-embed]' # local sentence-transformer embeddings
79
+ python -m pip install 'agentdatabase[mcp]' # stdio MCP server
80
+ python -m pip install 'agentdatabase[providers]' # Anthropic provider client
81
+ python -m pip install 'agentdatabase[notifications]' # Slack notifications
82
+ python -m pip install 'agentdatabase[evolution]' # WikiSkill and SkillOpt bridges
83
+ ```
84
+
85
+ Email notifications use the Python standard library. The `notifications` extra is needed for Slack.
86
+
87
+ ## Quick start
88
+
89
+ Pass a `memory_dir` or `path` when constructing the client:
90
+
91
+ ```python
92
+ from agentdb import AgentDB
93
+
94
+ # Creates config/, database/, and other workspace directories as needed.
95
+ db = AgentDB(memory_dir="./agentdb-memory")
96
+
97
+ record = db.write(
98
+ key="memory/working/response_style",
99
+ value="Prefer concise bullet points.",
100
+ origin="agent_inferred",
101
+ agent_id="assistant",
102
+ )
103
+
104
+ result = db.retrieve("How should I format the response?", agent_id="assistant")
105
+ print([record.value for record in result.records])
106
+ ```
107
+
108
+ The default workspace configuration is written to `config/memory.yaml`. Set `AGENTDB_MEMORY_DIR` or `AGENTDB_HOME` to choose a workspace through the environment.
109
+
110
+ ## Permissions and trust
111
+
112
+ Provide `permissions_path` to enable write/delete checks:
113
+
114
+ ```python
115
+ db = AgentDB(
116
+ memory_dir="./agentdb-memory",
117
+ permissions_path="./permissions.yaml",
118
+ )
119
+ ```
120
+
121
+ Example policy:
122
+
123
+ ```yaml
124
+ default_policy: deny
125
+ human_zone_prefixes:
126
+ - "skills/"
127
+ agents:
128
+ assistant:
129
+ can_write:
130
+ - "memory/working/"
131
+ cannot_write:
132
+ - "skills/"
133
+ ```
134
+
135
+ Important current limits:
136
+
137
+ - Without `permissions_path`, the permission router is not active.
138
+ - `read()` and `retrieve()` do not enforce `can_read`; do not treat that field as a read-access boundary.
139
+ - Agent-scoped retrieval is enabled for agents configured under `profile.agents` in `memory.yaml`; otherwise retrieval is not filtered by `agent_id`.
140
+ - The router governs calls through the client API; direct access to internal storage is outside that control path.
141
+ - The no-argument `AgentDB()` constructor currently selects SQLite's `:memory:` path, but initialization fails because the store opens separate short-lived connections. Use `memory_dir=` or `path=` instead.
142
+
143
+ ## Configuration and embeddings
144
+
145
+ `memory.yaml` uses a named profile with optional overrides. Built-in profiles are `budget_optimized`, `full_storage`, and `research`:
146
+
147
+ ```yaml
148
+ profile:
149
+ name: budget_optimized
150
+ agents:
151
+ assistant:
152
+ retrieval:
153
+ retrieve_limit: 10
154
+
155
+ # Embeddings are off unless enabled or supplied through the constructor.
156
+ embeddings:
157
+ enabled: true
158
+ # model: sentence-transformers/all-MiniLM-L6-v2
159
+ ```
160
+
161
+ Embeddings can also be enabled with `AgentDB(local_embed=True)` or a custom `embed_fn(text) -> list[float]`. They enable semantic ranking and embedding-based conflict checks. Local embeddings require the `local-embed` extra; embedding support is disabled by default.
162
+
163
+ ## Main API surfaces
164
+
165
+ - `AgentDB`: memory writes/reads/retrieval, `consolidate()`, `checkpoint()`, `write_compaction_summary()`, `record_outcome()`, `config`, and `config_for(agent_id)`.
166
+ - `db.lifecycle`: lifecycle sweeps, reinforcement, and outcome recording. Sweeps are not run by a background scheduler.
167
+ - `db.gateway`: in-process event subscriptions/dispatch, conflict queue, and skill proposals.
168
+ - `db.skills_api`: create, version, retrieve, archive, and inspect skill warnings.
169
+ - `db.system.agentdb_stats()`: corpus and outcome statistics.
170
+ - `db.audit_log.replay()`: replay persisted audit entries.
171
+ - `AgentDBBackend` (`from agentdb.backend import AgentDBBackend`): key/value `read`, `write`, `delete`, `list`, `grep`, and `glob` for a selected agent and trust zone.
172
+
173
+ Retrieval returns `RetrievalResult` with records, conflicts, authority override instructions, a token estimate, and a truncation flag. `retrieve_by_entities()` supports action-oriented lookups. Semantic matching requires embeddings; without them, retrieval uses the non-semantic signals and existing text/entity matching.
174
+
175
+ ## Runtime integrations
176
+
177
+ ### Model-agnostic middleware
178
+
179
+ `AgentDBMiddleware` (`from agentdb.adapters import AgentDBMiddleware`) provides `prepare_turn` / `finalize_turn` and `run_turn`, plus async variants. The async preparation path can inject skills, workspace information, and recent work context according to `RunnerCapabilities`; the synchronous path prepares memory context.
180
+
181
+ ### Claude
182
+
183
+ `AgentDBClaudeRuntime` supports synchronous model clients and an async Claude SDK client factory. `AgentDBClaudeMiddleware` remains available as a backward-compatible import. The adapter exposes a `PreToolUse` hook map through `get_sdk_hooks()`; the integrating application is responsible for registering that hook with its SDK/runtime.
184
+
185
+ ### Hermes
186
+
187
+ `AgentDBHermesProvider` implements Hermes's `MemoryProvider` interface. It supplies retrieval, turn persistence, skills context, and lifecycle hooks. Governance applies to AgentDB records; a post-write Hermes hook cannot veto a write already made to Hermes-native storage.
188
+
189
+ ### Other frameworks
190
+
191
+ No dedicated deepagents, LangGraph, CrewAI, OpenAI Agents, Google ADK, or AutoGen adapter is included. Use `AgentDBBackend` where the framework supports a pluggable key/value backend, or integrate `AgentDBMiddleware` at the runtime's own control points.
192
+
193
+ See [`docs/integrations/README.md`](docs/integrations/README.md) for integration guides.
194
+
195
+ ## Optional services
196
+
197
+ - **MCP:** `agentdb-mcp` starts a stdio server with `memory_write`, `memory_retrieve`, `conflict_queue`, and `memory_stats`. Set `AGENTDB_MEMORY_DIR` to select its workspace. HTTP transport is not implemented.
198
+ - **Anthropic ingestion:** `AnthropicProvider(db, client).sync(agent_id, limit=50)` ingests text message blocks as `provider_ingested` records.
199
+ - **Notifications:** configure email or Slack channels in `memory.yaml`; dispatch is live and in-process, not a durable queue.
200
+ - **Skill evolution:** `src/agentdb/skills/evolution/` contains WikiSkill and SkillOpt adapters for applying proposed or accepted skill versions.
201
+
202
+ ## Tests
203
+
204
+ ```bash
205
+ python -m pytest -q
206
+ ```
207
+
208
+ See [`docs/context/testing-strategy.md`](docs/context/testing-strategy.md) for focused test commands and [`docs/context/architecture-principles.md`](docs/context/architecture-principles.md) for the design constraints. The repository uses a `src/` layout and package imports such as `from agentdb import AgentDB`.
@@ -9,6 +9,7 @@ src/agentdatabase.egg-info/requires.txt
9
9
  src/agentdatabase.egg-info/top_level.txt
10
10
  src/agentdb/__init__.py
11
11
  src/agentdb/backend.py
12
+ src/agentdb/ingest.py
12
13
  src/agentdb/testing.py
13
14
  src/agentdb/adapters/__init__.py
14
15
  src/agentdb/adapters/capabilities.py
@@ -1,10 +1,10 @@
1
1
  from .middleware import AgentDBMiddleware
2
- from .capabilities import RunnerCapabilities, CLAUDE_CAPABILITIES, FIREWORKS_CAPABILITIES, LOCAL_CAPABILITIES
2
+ from .capabilities import RunnerCapabilities, CLAUDE_CAPABILITIES, SERVERLESS_CAPABILITIES, LOCAL_CAPABILITIES
3
3
 
4
4
  __all__ = [
5
5
  "AgentDBMiddleware",
6
6
  "RunnerCapabilities",
7
7
  "CLAUDE_CAPABILITIES",
8
- "FIREWORKS_CAPABILITIES",
8
+ "SERVERLESS_CAPABILITIES",
9
9
  "LOCAL_CAPABILITIES",
10
10
  ]
@@ -27,8 +27,10 @@ CLAUDE_CAPABILITIES = RunnerCapabilities(
27
27
  auto_elevate_threshold=3,
28
28
  )
29
29
 
30
- # Fireworks capabilities: partial injection
31
- FIREWORKS_CAPABILITIES = RunnerCapabilities(
30
+ # Serverless capabilities: provider-hosted, OpenAI-compatible runtimes with
31
+ # partial injection. Shared by any such provider (e.g. Fireworks, DeepInfra);
32
+ # name the tier, not the vendor, so providers are not coupled to each other.
33
+ SERVERLESS_CAPABILITIES = RunnerCapabilities(
32
34
  can_call_tools_mid_turn=False,
33
35
  can_write_mid_turn=False,
34
36
  has_native_memory=True,
@@ -63,6 +63,7 @@ class MemoryRecord:
63
63
  embedding: Optional[list[float]] = field(default=None, repr=False)
64
64
  consolidated: bool = False
65
65
  source_record_ids: list = field(default_factory=list)
66
+ session_id: Optional[str] = None
66
67
 
67
68
 
68
69
  @dataclass