agentdatabase 0.1.0__tar.gz → 0.3.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.
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/PKG-INFO +126 -53
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/README.md +114 -52
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/pyproject.toml +6 -1
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdatabase.egg-info/PKG-INFO +126 -53
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdatabase.egg-info/SOURCES.txt +13 -1
- agentdatabase-0.3.0/src/agentdatabase.egg-info/requires.txt +27 -0
- agentdatabase-0.3.0/src/agentdb/__init__.py +13 -0
- agentdatabase-0.3.0/src/agentdb/adapters/__init__.py +10 -0
- agentdatabase-0.3.0/src/agentdb/adapters/capabilities.py +52 -0
- agentdatabase-0.3.0/src/agentdb/adapters/claude_agent_sdk.py +234 -0
- agentdatabase-0.1.0/src/agentdb/adapters/claude_agent_sdk.py → agentdatabase-0.3.0/src/agentdb/adapters/middleware.py +304 -207
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/core/models.py +13 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/core/store.py +11 -2
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/core/system.py +37 -3
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/embeddings/provider.py +24 -13
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/gateway/__init__.py +74 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/governance/lifecycle_manager.py +168 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/interface/client.py +338 -29
- agentdatabase-0.3.0/src/agentdb/notifications/__init__.py +9 -0
- agentdatabase-0.3.0/src/agentdb/notifications/channels.py +104 -0
- agentdatabase-0.3.0/src/agentdb/notifications/dispatcher.py +138 -0
- agentdatabase-0.3.0/src/agentdb/providers/__init__.py +12 -0
- agentdatabase-0.3.0/src/agentdb/providers/anthropic.py +72 -0
- agentdatabase-0.3.0/src/agentdb/skills/evolution/__init__.py +5 -0
- agentdatabase-0.3.0/src/agentdb/skills/evolution/manager.py +31 -0
- agentdatabase-0.3.0/src/agentdb/skills/evolution/skillopt_adapter.py +130 -0
- agentdatabase-0.3.0/src/agentdb/skills/evolution/wikiskill_adapter.py +104 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/skills/skill_store.py +117 -13
- agentdatabase-0.1.0/src/agentdatabase.egg-info/requires.txt +0 -11
- agentdatabase-0.1.0/src/agentdb/__init__.py +0 -5
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/LICENSE +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/setup.cfg +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdatabase.egg-info/dependency_links.txt +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdatabase.egg-info/entry_points.txt +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdatabase.egg-info/top_level.txt +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/adapters/hermes.py +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/backend.py +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/core/__init__.py +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/core/directory_tracking.py +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/core/file_integrity.py +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/core/profiles.py +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/embeddings/__init__.py +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/embeddings/store.py +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/embeddings/text.py +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/gateway/adapter.py +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/governance/__init__.py +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/governance/conflict_detector.py +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/governance/permission_router.py +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/interface/__init__.py +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/interface/mcp_server.py +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/retrieval/__init__.py +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/retrieval/algorithm.py +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/skills/__init__.py +0 -0
- {agentdatabase-0.1.0 → agentdatabase-0.3.0}/src/agentdb/testing.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: agentdatabase
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.3.0
|
|
4
4
|
Summary: Governed memory layer for AI agents
|
|
5
5
|
Author-email: DatoSurf <team@datosurf.com>
|
|
6
6
|
License: AGPL-3.0
|
|
@@ -27,13 +27,24 @@ Provides-Extra: mcp
|
|
|
27
27
|
Requires-Dist: mcp<2.0,>=1.0; extra == "mcp"
|
|
28
28
|
Provides-Extra: local-embed
|
|
29
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"
|
|
30
41
|
Dynamic: license-file
|
|
31
42
|
|
|
32
43
|
# AgentDB
|
|
33
44
|
|
|
34
|
-
**
|
|
45
|
+
**An arbitration layer between agent inference and human intent.**
|
|
35
46
|
|
|
36
|
-
AgentDB
|
|
47
|
+
AgentDB governs what agents remember, what they're allowed to write, and when their inferences conflict with what humans have explicitly decided. It enforces a trust hierarchy at write time, provenance-weights recall at read time, and tracks versioned human instructions (skills) that agents cannot silently overwrite. Every write is validated before it lands. Every read returns a governed context package. The boundary is enforced at the memory layer — not by convention, not by prompt instructions, not by hoping agents behave.
|
|
37
48
|
|
|
38
49
|
> Every other memory product stores context. AgentDB governs it.
|
|
39
50
|
|
|
@@ -47,9 +58,9 @@ The full architecture pitch and the numbered design principles live in one canon
|
|
|
47
58
|
- Plan (active/open work): `/agentdb/docs/superpowers/plans/2026-06-06-agentdb-revised.md`
|
|
48
59
|
- Completed work tracker: `/agentdb/docs/superpowers/plans/completed-tasks.md`
|
|
49
60
|
|
|
50
|
-
## Current Repository Status (As Of 2026-10-
|
|
61
|
+
## Current Repository Status (As Of 2026-10-10)
|
|
51
62
|
|
|
52
|
-
Core governed memory loop is fully operational:
|
|
63
|
+
Core governed memory loop is fully operational. All major governance capabilities are implemented and test-covered: conflict detection (temporal + authority + semantic), budgeted retrieval, lifecycle management, memory consolidation, skill draft auto-proposal, context compaction, centralized config + profiles, email/Slack notifications, MCP server (stdio), Anthropic provider ingestor, two framework adapters (Claude SDK + Hermes), and YAML-configurable embeddings (`memory.yaml` `embeddings.enabled: true`). Only HTTP+SSE MCP transport remains deferred.
|
|
53
64
|
|
|
54
65
|
### Feature State Matrix
|
|
55
66
|
|
|
@@ -71,21 +82,27 @@ Core governed memory loop is fully operational: real conflict detection, budgete
|
|
|
71
82
|
| Feature area | State | Notes |
|
|
72
83
|
|---|---|---|
|
|
73
84
|
| Permission routing boundaries | Implemented | Write-time enforcement via `PermissionRouter`. |
|
|
74
|
-
| Write-time conflict detection (temporal + authority) | Implemented | `ConflictDetector` wired into `write()` — temporal conflicts auto-resolve in favour of recency; authority conflicts (agent vs. human-approved) auto-resolve in favour of human, flagged on retrieve.
|
|
85
|
+
| Write-time conflict detection (temporal + authority) | Implemented | `ConflictDetector` wired into `write()` — temporal conflicts auto-resolve in favour of recency; authority conflicts (agent vs. human-approved) auto-resolve in favour of human, flagged on retrieve. `agentdb_stats()` `conflict_pending_count` reflects unresolved conflicts live. |
|
|
75
86
|
| External-context conflict detection | Implemented | `external_context` param on `retrieve()` checks overlap between caller-supplied context and stored records; flags `external_conflict_detected` + `external_conflict_rate` stat. `override_instructions` still dead code — detection works, explicit overrides are not generated. |
|
|
76
|
-
| Reconciliation trigger orchestration + `db.gateway` | Implemented | `db.gateway.subscribe`/`dispatch` is the unified surface. `conflict_detected` dispatched by `write()`. `conversation_started` dispatched by both adapters at turn start. Conflict queue (`db.gateway.conflict_queue()`), proposal workflow (`propose`/`approve`/`reject`/`list_proposals`) all live here. |
|
|
77
|
-
|
|
|
87
|
+
| Reconciliation trigger orchestration + `db.gateway` | Implemented | `db.gateway.subscribe`/`dispatch` is the unified surface. `conflict_detected` dispatched by `write()`. `conversation_started` dispatched by both adapters at turn start; also seeds `SessionProfile` (always active) and auto-triggers consolidation at 7 days + 10 sessions. Conflict queue (`db.gateway.conflict_queue()`), proposal workflow (`propose`/`approve`/`reject`/`list_proposals`) all live here. |
|
|
88
|
+
| Session metadata + cross-repo isolation (`SessionProfile`) | Implemented | `SessionProfile` seeds at `conversation_started` (always active, no embeddings). `_classify_request_type()` sets `request_types` (rule-based, no LLM); `repos` is the last path segment of `working_dirs`. `retrieve()` filters candidates to repos the session has touched; records with no `working_dirs` always pass. `write()` expands the profile mid-session — pivoting to a new repo during a session opens that repo's memories automatically. |
|
|
89
|
+
| Skill–memory conflict signal (`skill_review_needed`) | Implemented (keyword + semantic) | Dispatched from `write()` on key/entity/repo-segment keyword overlap with a scoped skill. Fires at most once per skill per write. Semantic path fires when embeddings active and keyword didn't match — embedding is stored before conflict check runs. LLM-synthesized canonicals from `consolidate(llm_fn=...)` are also re-checked synchronously. |
|
|
90
|
+
| Embedding-backed semantic retrieval/conflicts | Implemented | Three activation paths — `embed_fn=` kwarg (any callable), `local_embed=True` flag, or `memory.yaml` `embeddings.enabled: true`. `EmbeddingStore` (SQLite-Vec) + `EmbeddingProvider` wired. Semantic retrieval and semantic skill–memory conflict detection both operational when embeddings active. Default model: `sentence-transformers/all-MiniLM-L6-v2` (requires `pip install 'agentdatabase[local-embed]'`). |
|
|
91
|
+
| Notification channels (email + Slack) | Implemented | `src/agentdb/notifications/`: `EmailChannel` (stdlib smtplib, no extra deps), `SlackChannel` (`slack-sdk` optional extra). `NotificationDispatcher` subscribes to gateway events and routes formatted messages; channel failures isolated. Configure via `memory.yaml` `notifications:` block. |
|
|
92
|
+
| Skill draft auto-proposal from consolidation | Implemented | `Gateway.auto_propose_from_cluster()` auto-fires when consolidation finds an ungoverned cluster. Deduplicates by stored `domain_words`; dispatches `skill_draft_proposed`. Approve via `db.gateway.approve(proposal_id)`. |
|
|
93
|
+
| Context compaction | Implemented | `db.checkpoint(agent_id, session_id)` and `db.write_compaction_summary(agent_id, session_id, summary)` write human_approved records that survive all lifecycle sweeps and are retrievable in future sessions for the same agent. |
|
|
78
94
|
|
|
79
95
|
#### Rank
|
|
80
96
|
|
|
81
97
|
| Feature area | State | Notes |
|
|
82
98
|
|---|---|---|
|
|
83
|
-
| Algorithm + skills
|
|
84
|
-
| Skills store +
|
|
85
|
-
| System stats surface | Implemented (
|
|
99
|
+
| Algorithm + skills complement | Implemented (initial) | Retrieval ranks memory records by provenance, recency, confidence, and causal signals. Skills are tracked database objects for conflict detection and staleness signalling — they are NOT injected into agent context. |
|
|
100
|
+
| Skills store + staleness signalling | Implemented | Versioned skills, staleness-based health scoring anchored on `updated_at` (content age). Stale-crossing fires `on_stale_crossing` callback, which dispatches `skill_stale` to gateway for async consumers (email, Slack, review queues). Check warnings via `db.skills_api.list_skill_warnings_for_agent()`. |
|
|
101
|
+
| System stats surface | Implemented | `db.system.agentdb_stats()` returns: `total_memories`, `avg_confidence`, `low_confidence_count`, `conflict_pending_count`, `retrieval_count_total`, `outcome_positive_rate`, `external_conflict_rate`, `total_skills`, `stale_skill_count`. |
|
|
86
102
|
| Entity-aware retrieval core (`entities`, `retrieve_by_entities`) | Implemented (initial) | Additive entity tagging and keyword-based entity retrieval are available in core. |
|
|
87
|
-
| Provider ingestors
|
|
103
|
+
| Provider ingestors | Partially implemented | `src/agentdb/providers/anthropic.py`: `AnthropicProvider(db, client).sync(agent_id, limit=50)` ingests assistant message text as `provider_ingested` memories; never overwrites `human_approved`. Optional extra: `pip install agentdb[providers]`. OpenAI + Google providers not yet built. |
|
|
88
104
|
| Lifecycle manager (`db.lifecycle`) | Implemented | `run_sweep()`: Step 0 archives expired records (`expiry_time ≤ now`); Step 1 optional confidence decay (off by default); Step 2 archives below `ARCHIVAL_THRESHOLD`; Step 3 archives past `STALENESS_DAYS`. `reinforce()` and `record_outcome()` also on `db.lifecycle`. `human_approved` records immune to all sweep operations. |
|
|
105
|
+
| Memory consolidation (`db.consolidate()`) | Implemented | `_lc_cluster()` groups near-duplicate records by key-word overlap. Canonical (highest confidence) survives, marked `consolidated=True` with `source_record_ids` tracing all originals. Lower-confidence copies archived. Auto-triggers at `conversation_started` when ≥7 days AND ≥10 sessions have elapsed since the last run per agent (`consolidation_state` table). `retrieve()` accepts `include_consolidated=False` to exclude consolidated records from injection. Optional `llm_fn=` synthesizes the canonical value; the LLM result is re-checked for skill conflict. `untracked_skill_candidate` dispatched when a cluster's topic has no governing skill. |
|
|
89
106
|
| `infer` flag + `expiry_time` on `write()` | Implemented | `infer=True` routes the raw value through a caller-supplied `infer_fn` before storage (raises `ValueError` if no `infer_fn` set). `expiry_time: datetime` sets a hard TTL; sweep archives once it passes. Both apply to `agent_inferred` only; `human_approved` records are immune. |
|
|
90
107
|
| Centralized config + profiles (`db.config`) | Implemented | `memory.yaml` drives all tunable defaults via mode-based profiles. Built-in profiles: `budget_optimized` (retrieve_limit=5, 2k chars, staleness=90d), `full_storage` (20, 12k, 90d), `research` (50, 24k, 180d, recency-first). User-defined profiles via `profiles:` block with optional `extends:`. `db.config` exposes the fully resolved dict. |
|
|
91
108
|
|
|
@@ -96,11 +113,11 @@ Core governed memory loop is fully operational: real conflict detection, budgete
|
|
|
96
113
|
| Query-driven retrieval into turn context | Implemented (Claude SDK + Hermes) | Both adapters retrieve at turn start via `prepare_turn`. `budget_tokens` param now wired end-to-end; `RetrievalResult.token_estimate` and `truncated` are live. |
|
|
97
114
|
| Action-driven retrieval (`entities`, `retrieve_by_entities`, `PreToolUse` hook) | Implemented (initial) | Core entity retrieval, adapter `pre_tool_use(...)`, and downstream hook-registration surface are implemented; automatic SDK attachment remains downstream integration work. |
|
|
98
115
|
| MCP server surface | Implemented (stdio) | `interface/mcp_server.py`: 4 tools (`memory_write`, `memory_retrieve`, `conflict_queue`, `memory_stats`). `agentdb-mcp` console script. HTTP+SSE transport deferred. |
|
|
99
|
-
|
|
|
116
|
+
| HTTP+SSE MCP transport | Deferred | stdio transport covers Claude Desktop. HTTP+SSE needed for browser-based/remote agents; deferred until a concrete integration is requested. |
|
|
100
117
|
|
|
101
118
|
Validation status:
|
|
102
119
|
- Editable install and package-style imports are validated via `pip install -e '.[dev]'`.
|
|
103
|
-
- `python -m pytest -q` →
|
|
120
|
+
- `python -m pytest -q` → 500 collected.
|
|
104
121
|
|
|
105
122
|
The rest of this README describes architecture intent and phased roadmap behavior.
|
|
106
123
|
|
|
@@ -163,6 +180,41 @@ Expected output:
|
|
|
163
180
|
world
|
|
164
181
|
```
|
|
165
182
|
|
|
183
|
+
### Configuring embeddings
|
|
184
|
+
|
|
185
|
+
Embeddings are **disabled by default**. Three ways to activate:
|
|
186
|
+
|
|
187
|
+
**1. YAML (recommended for persistent config)** — edit `memory.yaml` in your workspace:
|
|
188
|
+
|
|
189
|
+
```yaml
|
|
190
|
+
embeddings:
|
|
191
|
+
enabled: true
|
|
192
|
+
# model: sentence-transformers/all-MiniLM-L6-v2 # optional; this is the default
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Requires: `pip install 'agentdatabase[local-embed]'`. When `enabled: true` and no `model:` is set, the default `all-MiniLM-L6-v2` model is used.
|
|
196
|
+
|
|
197
|
+
**2. Constructor flag** — `local_embed=True` activates the default sentence-transformer:
|
|
198
|
+
|
|
199
|
+
```python
|
|
200
|
+
db = AgentDB(memory_dir="./memory", local_embed=True)
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
**3. Custom callable** — pass any function that returns a float vector:
|
|
204
|
+
|
|
205
|
+
```python
|
|
206
|
+
import openai
|
|
207
|
+
|
|
208
|
+
def embed(text: str) -> list[float]:
|
|
209
|
+
return openai.embeddings.create(input=text, model="text-embedding-3-small").data[0].embedding
|
|
210
|
+
|
|
211
|
+
db = AgentDB(memory_dir="./memory", embed_fn=embed)
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
**Precedence:** `embed_fn=` > `local_embed=True` > `memory.yaml` `enabled: true` > no embeddings.
|
|
215
|
+
|
|
216
|
+
When active, embeddings enable: semantic retrieval scoring, semantic skill–memory conflict detection, and session topic tracking.
|
|
217
|
+
|
|
166
218
|
Integration manuals:
|
|
167
219
|
|
|
168
220
|
- Index: `docs/integrations/README.md`
|
|
@@ -174,18 +226,19 @@ Integration manuals:
|
|
|
174
226
|
These are the developer-facing surfaces you can use immediately in the current implementation:
|
|
175
227
|
|
|
176
228
|
- `AgentDB` client (`from agentdb import AgentDB`)
|
|
177
|
-
- `write(key, value, origin, agent_id, infer=False, expiry_time=None
|
|
229
|
+
- `write(key, value, origin, agent_id, session_id=..., working_dirs=..., entities=..., confidence=..., infer=False, expiry_time=None)` — `session_id` + `working_dirs` expand `SessionProfile` and trigger `skill_review_needed` on overlap
|
|
178
230
|
- `read(key, agent_id)`
|
|
179
|
-
- `retrieve(query, agent_id, limit=..., budget_tokens=..., external_context=..., session_id
|
|
231
|
+
- `retrieve(query, agent_id, limit=..., budget_tokens=..., external_context=..., session_id=..., working_dirs=..., include_consolidated=True)` — `include_consolidated=False` excludes consolidated canonical records from injection
|
|
180
232
|
- `retrieve_by_entities(entities, agent_id, session_id=...)`
|
|
233
|
+
- `consolidate(agent_id, since_hours=24, min_cluster_size=2, skill_candidate_threshold=5, llm_fn=None)` — cluster near-duplicates, archive lower-confidence copies, mark canonical `consolidated=True` with `source_record_ids`; re-checks skill conflict for LLM-synthesized canonicals
|
|
181
234
|
- `record_outcome(session_id, agent_id, outcome_type, outcome_value)` — backward-compat alias for `db.lifecycle.record_outcome()`
|
|
182
235
|
- `system.agentdb_stats()`
|
|
183
236
|
- `audit_log.replay(from_sequence=0)`
|
|
184
237
|
- `lifecycle` — `run_sweep()`, `reinforce(record_id)`, `record_outcome(...)`
|
|
185
|
-
- `gateway` — `subscribe(trigger, handler)`, `dispatch(trigger, ...)`, `conflict_queue()`, `propose(...)`, `approve(...)`, `reject(...)`, `list_proposals(...)`
|
|
238
|
+
- `gateway` — `subscribe(trigger, handler)`, `dispatch(trigger, ...)`, `conflict_queue()`, `propose(...)`, `approve(...)`, `reject(...)`, `list_proposals(...)`; `conversation_started` accepts `session_id`, `agent_id`, `opening_message`, `working_dirs`
|
|
186
239
|
- `config` — returns the fully resolved config dict (mode defaults + yaml overrides)
|
|
187
240
|
- `skills_api` — `create_skill`, `update_skill_version`, `get_skill`, `archive_skill`, `list_stale_skills_for_agent`, `list_skill_warnings_for_agent`
|
|
188
|
-
- optional initialization: `tracking_directories`, `tracking_root`, `tracking_max_files_per_directory`, `infer_fn`, `memory_dir`
|
|
241
|
+
- optional initialization: `tracking_directories`, `tracking_root`, `tracking_max_files_per_directory`, `infer_fn`, `memory_dir`, `embed_fn` (custom embedding callable), `local_embed` (bool — activates `LocalEmbeddingProvider` with default sentence-transformer model)
|
|
189
242
|
- `AgentDBBackend` (`from agentdb.backend import AgentDBBackend`)
|
|
190
243
|
- `read`, `write`, `delete`, `list`, `grep`, `glob`
|
|
191
244
|
- Adapters currently implemented under `src/agentdb/adapters/`
|
|
@@ -346,15 +399,20 @@ db.skills_api.create_skill(
|
|
|
346
399
|
# authored_by is always "human" — SkillsAPI.create_skill() sets it, there's no way to pass agent-authored skills in.
|
|
347
400
|
|
|
348
401
|
# 45 days later — schema changed, skill not updated:
|
|
349
|
-
|
|
350
|
-
result.skill_warnings
|
|
402
|
+
warnings = db.skills_api.list_skill_warnings_for_agent("analytics_agent")
|
|
351
403
|
# → ["Skill 'analytics-schema-v1' is stale (health_score=0.42)"]
|
|
404
|
+
|
|
405
|
+
# Skills are not injected into retrieve() — they are governance objects.
|
|
406
|
+
# Use the warning signal to trigger a skill review workflow.
|
|
352
407
|
```
|
|
353
408
|
|
|
354
|
-
A health score below 0.6
|
|
409
|
+
A health score below 0.6 triggers a staleness warning surfaced via `db.skills_api.list_skill_warnings_for_agent()` and dispatched via the `on_stale_crossing` callback (wired to `db.gateway` for async consumers). Skills are tracked database objects — they are not injected into agent context, and `RetrievalResult` carries no skill fields.
|
|
355
410
|
|
|
356
411
|
**What degrades the health score today:**
|
|
357
|
-
- Days since
|
|
412
|
+
- Days since `updated_at` (when skill content last changed), half-life 30 days — the only implemented factor
|
|
413
|
+
|
|
414
|
+
**Conflict signal (`skill_review_needed`) — implemented:**
|
|
415
|
+
- `write()` dispatches `skill_review_needed` whenever a new record's key, entity list, or repo segment overlaps keyword-level with a scoped skill. This is a 12b signal — it tells a subscriber that agent-inferred content may be drifting from what the skill declares. Keyword check runs first; semantic check (Phase 4) runs only when embeddings are active and keyword didn't fire.
|
|
358
416
|
|
|
359
417
|
**Planned, not yet implemented:**
|
|
360
418
|
- Unresolved conflicts linked to the skill (no conflict linkage exists on skills yet)
|
|
@@ -362,23 +420,23 @@ A health score below 0.6 surfaces a staleness warning in every retrieval result.
|
|
|
362
420
|
|
|
363
421
|
**Current limitation (Phase 2):** Entity drift detection is keyword-based — a skill that uses a synonym for a deprecated entity will not be flagged. Semantic entity matching is Phase 5 scope. This limitation is documented in LIMITATIONS.md.
|
|
364
422
|
|
|
365
|
-
**
|
|
423
|
+
**Skill draft reconciliation pipeline** — implemented. When consolidation surfaces a cluster with no governing skill, `Gateway.auto_propose_from_cluster()` auto-proposes a skill draft. Deduplicates against existing proposals via stored `domain_words`. Human approves via `db.gateway.approve(proposal_id)` or rejects via `db.gateway.reject(proposal_id)`. The approval step is the only path that can create or modify a real skill.
|
|
366
424
|
|
|
367
425
|
### Why the algorithm and skills belong together
|
|
368
426
|
|
|
369
427
|
The retrieval algorithm and the governed skills system are one foundation, not two unrelated features.
|
|
370
428
|
|
|
371
|
-
- The algorithm answers: which
|
|
372
|
-
- Skills answer:
|
|
429
|
+
- The algorithm answers: which memory records are most relevant to the action the agent is about to take?
|
|
430
|
+
- Skills answer: is the agent's current inference in conflict with what humans have explicitly decided — and is that guidance still current?
|
|
373
431
|
|
|
374
432
|
In practice, AgentDB is strongest when these work together:
|
|
375
433
|
|
|
376
434
|
1. memory records capture facts, context, prior outcomes, and relevant assets
|
|
377
435
|
2. the ranking algorithm decides what matters now
|
|
378
|
-
3. skills
|
|
379
|
-
4. the runtime injects
|
|
436
|
+
3. skills provide the authoritative baseline for detecting when agent behavior drifts from human intent
|
|
437
|
+
4. the runtime injects governed memory records as compact action-ready context; skills govern from outside the injection path
|
|
380
438
|
|
|
381
|
-
That
|
|
439
|
+
That is the arbitration contract. The goal is not to accumulate more memory artifacts. The goal is to ensure that when an agent acts, its memory reflects what humans actually intend — and that conflicts and drift are surfaced before they cause harm.
|
|
382
440
|
|
|
383
441
|
---
|
|
384
442
|
|
|
@@ -428,16 +486,19 @@ Every record in AgentDB carries a full biography — not just a value:
|
|
|
428
486
|
Implemented today:
|
|
429
487
|
|
|
430
488
|
```
|
|
431
|
-
key
|
|
432
|
-
value
|
|
433
|
-
origin
|
|
434
|
-
trust_level
|
|
435
|
-
confidence
|
|
436
|
-
entities
|
|
437
|
-
last_retrieved
|
|
438
|
-
conflict_id
|
|
439
|
-
expiry_time
|
|
440
|
-
inferred
|
|
489
|
+
key → addressable path e.g. "memory/working/pref_format"
|
|
490
|
+
value → the memory content
|
|
491
|
+
origin → human_approved | agent_inferred | provider_ingested
|
|
492
|
+
trust_level → sealed | human | agent | provider (derived from origin; "sealed" is unused so far)
|
|
493
|
+
confidence → float 0–1, decays over time unless reinforced
|
|
494
|
+
entities → list of canonical identifiers (file paths, model names) for action-driven retrieval
|
|
495
|
+
last_retrieved → drives the ranker's recency signal
|
|
496
|
+
conflict_id → populated by ConflictDetector at write time when a temporal or authority conflict is detected
|
|
497
|
+
expiry_time → optional hard TTL (datetime); lifecycle sweep archives once it passes (agent_inferred only)
|
|
498
|
+
inferred → bool; true when the value was derived by infer_fn rather than stored verbatim
|
|
499
|
+
working_dirs → list of absolute paths; used by repo filter to scope retrieve() to the current session's repos
|
|
500
|
+
consolidated → bool; True when this record is the surviving canonical of a consolidation cluster. retrieve() can exclude these via include_consolidated=False.
|
|
501
|
+
source_record_ids → list of record IDs merged into this canonical during consolidation. Empty on normal records.
|
|
441
502
|
```
|
|
442
503
|
|
|
443
504
|
Planned, not yet on the record: `tier`, `expiry_policy`, `audit_sequence`, `embedding_version`, `user_id`, `session_id`. See `docs/context/database-schema.md` for the full column-by-column reference.
|
|
@@ -468,7 +529,7 @@ Detection runs at write time, not read time — by the time an agent is mid-exec
|
|
|
468
529
|
|---|---|---|
|
|
469
530
|
| **Temporal** | **Implemented** | Auto-resolved in favour of recency. Logged. `conflict_id` stamped on both records. |
|
|
470
531
|
| **Authority** | **Implemented** | Agent-inferred contradicts human-approved → auto-resolved in favour of human. `override_instructions` populated in `RetrievalResult`. `conflict_detected` dispatched via `db.gateway`. |
|
|
471
|
-
| **Semantic** |
|
|
532
|
+
| **Semantic** | **Implemented** | Active when embeddings are configured. `ConflictDetector` runs cosine similarity check when `embed_fn=`, `local_embed=True`, or `memory.yaml` `embeddings.enabled: true` is set. |
|
|
472
533
|
|
|
473
534
|
`ConflictDetector` (`governance/conflict_detector.py`) is wired into `write()`. On conflict: both records get `conflict_id`, the conflict is stored, and `db.gateway.dispatch("conflict_detected", ...)` fires so any subscriber (Slack notifier, MCP consumer, etc.) is immediately notified.
|
|
474
535
|
|
|
@@ -484,7 +545,7 @@ result.override_instructions # human-approved wins messages for authority confl
|
|
|
484
545
|
|
|
485
546
|
External-context detection (caller-supplied context vs. stored records) is a separate, narrower check available via `external_context=` on `retrieve()` — it flags `external_conflict_detected` audit events but does not interact with the stored `conflicts` table.
|
|
486
547
|
|
|
487
|
-
**
|
|
548
|
+
**Note:** Structural conflicts (temporal + authority) are always detected. Semantic conflict detection requires embeddings to be active — configure via `embed_fn=` kwarg, `local_embed=True`, or `memory.yaml` `embeddings.enabled: true`.
|
|
488
549
|
|
|
489
550
|
---
|
|
490
551
|
|
|
@@ -511,7 +572,7 @@ Signal weights (all configurable, enforced to sum to 1.0 in `MultiSignalRanker`'
|
|
|
511
572
|
| Semantic (cosine similarity) | 0.0 | No — Mem0 baseline |
|
|
512
573
|
| Workspace (working-directory overlap) | 0.0 | **Yes** |
|
|
513
574
|
|
|
514
|
-
**Target redistribution
|
|
575
|
+
**Target redistribution when embeddings are configured** (`embed_fn=`, `local_embed=True`, or `memory.yaml` `embeddings.enabled: true`):
|
|
515
576
|
|
|
516
577
|
| Signal | Weight |
|
|
517
578
|
|---|---|
|
|
@@ -588,17 +649,24 @@ Action-driven retrieval uses the existing keyword ranker and works with Phase 2
|
|
|
588
649
|
AgentDB does not compete with provider-native memory. It governs it.
|
|
589
650
|
|
|
590
651
|
```python
|
|
591
|
-
#
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
652
|
+
# Anthropic provider — implemented
|
|
653
|
+
from agentdb.providers.anthropic import AnthropicProvider
|
|
654
|
+
import anthropic
|
|
655
|
+
|
|
656
|
+
client = anthropic.Anthropic(api_key="...")
|
|
657
|
+
provider = AnthropicProvider(db=db, client=client)
|
|
658
|
+
ingested = provider.sync(agent_id="assistant", limit=50) # returns count written
|
|
659
|
+
|
|
660
|
+
# OpenAI + Google providers — not yet built
|
|
661
|
+
db.providers.openai.sync(agent_id="assistant") # NOT YET IMPLEMENTED
|
|
662
|
+
db.providers.google.sync() # NOT YET IMPLEMENTED
|
|
595
663
|
```
|
|
596
664
|
|
|
597
|
-
|
|
665
|
+
`src/agentdb/providers/anthropic.py` is implemented. Requires `pip install 'agentdatabase[providers]'`. `AnthropicProvider.sync()` ingests recent assistant message text as `provider_ingested` memories; never overwrites `human_approved`. OpenAI and Google providers are not yet built.
|
|
598
666
|
|
|
599
|
-
All
|
|
667
|
+
All providers write with `origin=provider_ingested`, `trust_level=provider`. No provider memory is ever promoted to `human_approved` — the boundary is enforced at ingestion.
|
|
600
668
|
|
|
601
|
-
**Current limitation:** All
|
|
669
|
+
**Current limitation:** All providers use polling. Push subscription is deferred until providers expose push APIs.
|
|
602
670
|
|
|
603
671
|
---
|
|
604
672
|
|
|
@@ -640,10 +708,12 @@ db.system.agentdb_stats()
|
|
|
640
708
|
# "total_memories": 1847,
|
|
641
709
|
# "avg_confidence": 0.74,
|
|
642
710
|
# "low_confidence_count": 12, # confidence < 0.5
|
|
643
|
-
# "conflict_pending_count":
|
|
711
|
+
# "conflict_pending_count": 3, # live count of unresolved conflicts
|
|
644
712
|
# "outcome_positive_rate": 0.87, # None until at least 10 outcomes are recorded
|
|
645
713
|
# "retrieval_count_total": 4021,
|
|
646
714
|
# "external_conflict_rate": None, # None until at least one external-context retrieve happens
|
|
715
|
+
# "total_skills": 5, # active skills in skills.sqlite
|
|
716
|
+
# "stale_skill_count": 1, # skills with health_score < 0.6
|
|
647
717
|
# }
|
|
648
718
|
```
|
|
649
719
|
|
|
@@ -693,9 +763,10 @@ Agents not listed are denied all writes (`default_policy: deny`). Wildcard match
|
|
|
693
763
|
| Confidence decay | Agent-inferred memory, configurable rate (off by default) | Score reduced per sweep cycle | **Implemented** (off by default — ranking already applies recency decay at read time, making stored decay often redundant) |
|
|
694
764
|
| Staleness archival | Not retrieved within `staleness_days` (default 90) | Archived, excluded from retrieval | **Implemented** |
|
|
695
765
|
| Confidence threshold | Record confidence falls below `archival_threshold` (default 0.10) | Archived | **Implemented** |
|
|
696
|
-
| Skill staleness | Skill health score below 0.6 |
|
|
766
|
+
| Skill staleness | Skill health score crosses below 0.6 (anchored on `updated_at`) | `on_stale_crossing` callback fires once; warning surfaced via `db.skills_api.list_skill_warnings_for_agent()`; skill not archived automatically | **Implemented** (`skill_stale` 12b gateway dispatch pending) |
|
|
697
767
|
| Reinforcement | Positive outcome signal | Confidence boosted, decay clock reset | **Implemented** via `db.lifecycle.reinforce(record_id)` and `db.lifecycle.record_outcome(...)` |
|
|
698
768
|
| Human revocation | Explicit SDK delete | Archived with audit-log entry; history preserved | **Implemented** via `AgentDB.delete()` |
|
|
769
|
+
| Memory consolidation | 7 days AND 10+ sessions since last run (auto), or explicit `db.consolidate()` | Near-duplicate records clustered by key-word overlap; lower-confidence copies archived; canonical marked `consolidated=True` with `source_record_ids` provenance; `untracked_skill_candidate` dispatched when no skill governs the domain | **Implemented** — `human_approved` records immune; idempotent (second pass on same agent archives nothing) |
|
|
699
770
|
|
|
700
771
|
**`human_approved` records are immune to all sweep operations** — no decay, no staleness archival, no TTL expiry, regardless of field values.
|
|
701
772
|
|
|
@@ -818,16 +889,18 @@ db.record_outcome(
|
|
|
818
889
|
|
|
819
890
|
3. **Memories that consistently precede positive outcomes** have their confidence boosted (up to +0.05 per outcome, capped at +0.1). Memories that precede failures are gently decayed (−0.02 per negative outcome). The agent gets better at knowing what to trust.
|
|
820
891
|
|
|
821
|
-
4. **The corpus quality dashboard** answers "is this agent's memory getting better?" — actual current return shape (
|
|
892
|
+
4. **The corpus quality dashboard** answers "is this agent's memory getting better?" — actual current return shape (`outcome_positive_rate` is `None` under 10 outcomes):
|
|
822
893
|
|
|
823
894
|
```python
|
|
824
895
|
db.system.agentdb_stats()
|
|
825
896
|
# {
|
|
826
897
|
# "avg_confidence": 0.81, # trending up = memory improving
|
|
827
898
|
# "low_confidence_count": 3, # records at risk of archival
|
|
828
|
-
# "conflict_pending_count":
|
|
899
|
+
# "conflict_pending_count": 2, # live count of unresolved conflicts
|
|
829
900
|
# "outcome_positive_rate": 0.87, # 87% of tasks completed without correction (once >=10 outcomes recorded)
|
|
830
901
|
# "retrieval_count_total": 412,
|
|
902
|
+
# "total_skills": 4,
|
|
903
|
+
# "stale_skill_count": 0,
|
|
831
904
|
# }
|
|
832
905
|
```
|
|
833
906
|
|
|
@@ -835,7 +908,7 @@ db.system.agentdb_stats()
|
|
|
835
908
|
|
|
836
909
|
Provider-ingested memories can decay from negative outcomes but cannot be boosted — they are external data, not learned knowledge.
|
|
837
910
|
|
|
838
|
-
**Context compaction
|
|
911
|
+
**Context compaction is implemented.** `db.checkpoint(agent_id, session_id)` and `db.write_compaction_summary(agent_id, session_id, summary)` write `human_approved` records (key: `memory/compaction/{type}/{session_id}`) that survive all lifecycle sweeps and are retrievable by any future session for the same agent. Framework adapters call these before context truncation to preserve cross-session continuity.
|
|
839
912
|
|
|
840
913
|
---
|
|
841
914
|
|