agentdatabase 0.1.0__tar.gz → 0.2.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 (51) hide show
  1. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/PKG-INFO +126 -53
  2. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/README.md +114 -52
  3. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/pyproject.toml +6 -1
  4. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdatabase.egg-info/PKG-INFO +126 -53
  5. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdatabase.egg-info/SOURCES.txt +10 -1
  6. agentdatabase-0.2.0/src/agentdatabase.egg-info/requires.txt +27 -0
  7. agentdatabase-0.2.0/src/agentdb/__init__.py +13 -0
  8. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/core/models.py +13 -0
  9. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/core/store.py +11 -2
  10. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/core/system.py +37 -3
  11. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/embeddings/provider.py +24 -13
  12. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/gateway/__init__.py +74 -0
  13. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/governance/lifecycle_manager.py +168 -0
  14. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/interface/client.py +338 -29
  15. agentdatabase-0.2.0/src/agentdb/notifications/__init__.py +9 -0
  16. agentdatabase-0.2.0/src/agentdb/notifications/channels.py +104 -0
  17. agentdatabase-0.2.0/src/agentdb/notifications/dispatcher.py +138 -0
  18. agentdatabase-0.2.0/src/agentdb/providers/__init__.py +12 -0
  19. agentdatabase-0.2.0/src/agentdb/providers/anthropic.py +72 -0
  20. agentdatabase-0.2.0/src/agentdb/skills/evolution/__init__.py +5 -0
  21. agentdatabase-0.2.0/src/agentdb/skills/evolution/manager.py +31 -0
  22. agentdatabase-0.2.0/src/agentdb/skills/evolution/skillopt_adapter.py +130 -0
  23. agentdatabase-0.2.0/src/agentdb/skills/evolution/wikiskill_adapter.py +104 -0
  24. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/skills/skill_store.py +117 -13
  25. agentdatabase-0.1.0/src/agentdatabase.egg-info/requires.txt +0 -11
  26. agentdatabase-0.1.0/src/agentdb/__init__.py +0 -5
  27. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/LICENSE +0 -0
  28. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/setup.cfg +0 -0
  29. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdatabase.egg-info/dependency_links.txt +0 -0
  30. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdatabase.egg-info/entry_points.txt +0 -0
  31. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdatabase.egg-info/top_level.txt +0 -0
  32. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/adapters/claude_agent_sdk.py +0 -0
  33. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/adapters/hermes.py +0 -0
  34. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/backend.py +0 -0
  35. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/core/__init__.py +0 -0
  36. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/core/directory_tracking.py +0 -0
  37. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/core/file_integrity.py +0 -0
  38. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/core/profiles.py +0 -0
  39. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/embeddings/__init__.py +0 -0
  40. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/embeddings/store.py +0 -0
  41. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/embeddings/text.py +0 -0
  42. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/gateway/adapter.py +0 -0
  43. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/governance/__init__.py +0 -0
  44. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/governance/conflict_detector.py +0 -0
  45. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/governance/permission_router.py +0 -0
  46. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/interface/__init__.py +0 -0
  47. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/interface/mcp_server.py +0 -0
  48. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/retrieval/__init__.py +0 -0
  49. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/retrieval/algorithm.py +0 -0
  50. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/skills/__init__.py +0 -0
  51. {agentdatabase-0.1.0 → agentdatabase-0.2.0}/src/agentdb/testing.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: agentdatabase
3
- Version: 0.1.0
3
+ Version: 0.2.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
- **A governed memory layer that keeps agent memory actionable.**
45
+ **An arbitration layer between agent inference and human intent.**
35
46
 
36
- AgentDB is designed to improve agent behavior without becoming another layer of operational overhead. It governs what memory is trusted, keeps relevant memory assets in sync, and injects the right context or instructions when an agent is about to act. 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.
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-04)
61
+ ## Current Repository Status (As Of 2026-10-10)
51
62
 
52
- Core governed memory loop is fully operational: real conflict detection, budgeted retrieval, lifecycle management, centralized config + profiles, MCP server (stdio/Claude Desktop), and two adapters (Claude SDK + Hermes) are all shipped and test-covered. Phase 3 (embeddings/semantic search) is deliberately deferred until the loop proves its value in production. Provider ingestors (Phase 6) and additional framework adapters (Phase 4 Task 15) remain pending.
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. Semantic conflict detection is Phase 4 (requires embeddings). |
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
- | Embedding-backed semantic retrieval/conflicts | Planned (Phase 4) | Current retrieval is keyword/provenance/confidence/recency based; embeddings are only justified if they improve action quality. |
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 blend for action quality | Implemented (initial) | Retrieval ranks memory; governed skills add maintained guidance during retrieval results. |
84
- | Skills store + health warnings | Implemented | Versioned skills, staleness-based health scoring, warnings on retrieve. |
85
- | System stats surface | Implemented (initial) | Includes retrieval/outcome/conflict-rate aggregates. |
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 (Anthropic/OpenAI/Google sync) | Planned (Phase 3) | Architecture intent documented; module surface pending. Deliberately deferred — validating core loop with Claude SDK + Hermes in production first. |
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
- | Hardening and production controls | Planned (Phase 6) | Roadmap-only at this snapshot. |
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` → 277 passed.
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
- result = db.retrieve(query="revenue breakdown", agent_id="analytics_agent")
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 surfaces a staleness warning in every retrieval result. The agent sees the warning before acting on the skill content.
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 last retrieval (staleness decay, half-life 30 days) — the only implemented factor
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
- **Planned (Task 13, not started, blocked on Phase 4 embeddings):** a skill draft reconciliation pipeline — an agent can *propose* a new skill or an update to an existing one (written as an ordinary agent-inferred memory record, never touching `skills.sqlite` directly), which gets reconciled against other pending drafts, the target skill, and recently-changed files before a human explicitly approves or rejects it. Proposing is async (notifies a reviewer); only the approval step can ever create or modify a real skill. See the plan for the full design.
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 memories or instructions are most relevant to the action the agent is about to take?
372
- - Skills answer: which durable guidance should the agent trust when that action happens?
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 add governed, maintained instructions on top of those facts
379
- 4. the runtime injects both as compact action-ready context
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 blend is the development foundation for AgentDB. The goal is not to accumulate more memory artifacts. The goal is to turn memory into better decisions, fewer conflicting instructions, and more accurate actions.
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 → addressable path e.g. "memory/working/pref_format"
432
- value → the memory content
433
- origin → human_approved | agent_inferred | provider_ingested
434
- trust_level → sealed | human | agent | provider (derived from origin; "sealed" is unused so far)
435
- confidence → float 0–1, decays over time unless reinforced
436
- entities → list of canonical identifiers (file paths, model names) for action-driven retrieval
437
- last_retrieved → drives the ranker's recency signal
438
- conflict_id → populated by ConflictDetector at write time when a temporal or authority conflict is detected
439
- expiry_time → optional hard TTL (datetime); lifecycle sweep archives once it passes (agent_inferred only)
440
- inferred → bool; true when the value was derived by infer_fn rather than stored verbatim
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** | Planned (Phase 4) | Requires embeddings — deferred. |
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
- **Known limitation:** semantic conflict detection (same-authority, situationally contradictory) requires Phase 4 embeddings. Until then, only temporal and authority conflicts are detected.
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 once Phase 4 activates embeddings** (not active yet):
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
- # Provider memory flows INTO AgentDB, not around it
592
- db.providers.anthropic.sync(memory_store_id="ms_abc123") # NOT YET IMPLEMENTED
593
- db.providers.openai.sync(agent_id="assistant") # NOT YET IMPLEMENTED
594
- db.providers.google.sync() # Vertex AI MemoryBankService — NOT YET IMPLEMENTED
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
- No `src/agentdb/providers/` directory exists yet (Phase 3, gated behind the core loop stabilizing — see the plan's Current Status). The interface above is the target shape.
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 three providers write with `origin=provider_ingested`, `trust_level=provider`. No provider memory is ever promoted to `human_approved` — the boundary is enforced at ingestion.
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 three providers use polling. Push subscription is deferred until providers expose push APIs.
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": 0, # hardcoded 0 — conflict tracking doesn't exist yet (see Conflict detection above)
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 | Warning surfaced in retrieval; skill not archived automatically | **Implemented** |
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 (see "System tables" above for the full field list; `conflict_pending_count` is hardcoded `0` and `outcome_positive_rate` is `None` under 10 outcomes, since neither conflict tracking nor a small-sample guard-free rate would be trustworthy yet):
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": 0, # hardcoded — no conflict tracking yet
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 handling is planned, not yet implemented.** No `checkpoint()` or `write_compaction_summary()` method exists in the codebase today. The intent: promote important working memory to episodic storage before compaction fires, and persist the framework's compressed summary as a durable episodic record, both logged to the audit trail with a compaction boundary marker, with a modest provenance boost for compaction summaries since they're derived from real conversation rather than pure inference.
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