echo-mem 0.5.7__tar.gz → 0.6.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.
- {echo_mem-0.5.7/src/echo_mem.egg-info → echo_mem-0.6.0}/PKG-INFO +60 -4
- {echo_mem-0.5.7 → echo_mem-0.6.0}/README.md +59 -3
- {echo_mem-0.5.7 → echo_mem-0.6.0}/pyproject.toml +1 -1
- {echo_mem-0.5.7 → echo_mem-0.6.0/src/echo_mem.egg-info}/PKG-INFO +60 -4
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_mem.egg-info/SOURCES.txt +39 -1
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/attestation.py +84 -23
- echo_mem-0.6.0/src/echo_memory/cli/exchange.py +605 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/export.py +1 -4
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/graph.py +1 -4
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/main.py +26 -2
- echo_mem-0.6.0/src/echo_memory/cli/trust.py +793 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/erasure.py +65 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/eval/backends/echo.py +18 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/eval/external.py +304 -9
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/eval/retrieval.py +52 -12
- echo_mem-0.6.0/src/echo_memory/eval/scratchpad_eval.py +309 -0
- echo_mem-0.6.0/src/echo_memory/events/__init__.py +54 -0
- echo_mem-0.6.0/src/echo_memory/events/envelope.py +275 -0
- echo_mem-0.6.0/src/echo_memory/events/inbox.py +429 -0
- echo_mem-0.6.0/src/echo_memory/exchange/__init__.py +20 -0
- echo_mem-0.6.0/src/echo_memory/exchange/bundle.py +489 -0
- echo_mem-0.6.0/src/echo_memory/exchange/importer.py +884 -0
- echo_mem-0.6.0/src/echo_memory/exchange/redact.py +273 -0
- echo_mem-0.6.0/src/echo_memory/exchange/sign.py +420 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/infra/db.py +48 -0
- echo_mem-0.6.0/src/echo_memory/infra/graph_gate.py +36 -0
- echo_mem-0.6.0/src/echo_memory/infra/graphlock.py +256 -0
- echo_mem-0.6.0/src/echo_memory/infra/metrics.py +320 -0
- echo_mem-0.6.0/src/echo_memory/infra/provider.py +109 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/ingestion/embeddings.py +67 -7
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/ingestion/neighbourhood.py +16 -2
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/ingestion/write_episode.py +10 -0
- echo_mem-0.6.0/src/echo_memory/intelligence/__init__.py +62 -0
- echo_mem-0.6.0/src/echo_memory/intelligence/lessons.py +473 -0
- echo_mem-0.6.0/src/echo_memory/intelligence/naming.py +95 -0
- echo_mem-0.6.0/src/echo_memory/intelligence/outcomes.py +531 -0
- echo_mem-0.6.0/src/echo_memory/intelligence/vocabulary.py +125 -0
- echo_mem-0.6.0/src/echo_memory/migrations/versions/0031_evidence.py +143 -0
- echo_mem-0.6.0/src/echo_memory/migrations/versions/0032_fact_verification.py +178 -0
- echo_mem-0.6.0/src/echo_memory/migrations/versions/0033_event_inbox.py +137 -0
- echo_mem-0.6.0/src/echo_memory/migrations/versions/0034_decision_vocabulary.py +96 -0
- echo_mem-0.6.0/src/echo_memory/migrations/versions/0035_bundle_registry.py +146 -0
- echo_mem-0.6.0/src/echo_memory/migrations/versions/0036_hardening_indexes.py +96 -0
- echo_mem-0.6.0/src/echo_memory/migrations/versions/0037_event_inbox_scoped_key.py +113 -0
- echo_mem-0.6.0/src/echo_memory/migrations/versions/0038_bundle_registry_scoped_key.py +130 -0
- echo_mem-0.6.0/src/echo_memory/retrieval/across.py +286 -0
- echo_mem-0.6.0/src/echo_memory/retrieval/context.py +182 -0
- echo_mem-0.6.0/src/echo_memory/retrieval/envelope.py +214 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/retrieval/query_memory.py +117 -6
- echo_mem-0.6.0/src/echo_memory/retrieval/routing.py +483 -0
- echo_mem-0.6.0/src/echo_memory/retrieval/scratchpad.py +176 -0
- echo_mem-0.6.0/src/echo_memory/trust/__init__.py +86 -0
- echo_mem-0.6.0/src/echo_memory/trust/evidence.py +234 -0
- echo_mem-0.6.0/src/echo_memory/trust/states.py +111 -0
- echo_mem-0.6.0/src/echo_memory/trust/vattest.py +431 -0
- echo_mem-0.6.0/src/echo_memory/trust/verify.py +215 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/LICENSE +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/NOTICE +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/setup.cfg +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_mem.egg-info/dependency_links.txt +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_mem.egg-info/entry_points.txt +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_mem.egg-info/requires.txt +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_mem.egg-info/top_level.txt +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/__init__.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/audit/__init__.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/audit/get_audit_log.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/__init__.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/adopt.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/analyse.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/benchmark.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/calibrate.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/connect.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/dashboard.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/dashboard_html.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/distil.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/forget.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/health.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/hooks.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/infer_causal.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/initdb.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/install.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/judge.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/llm.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/merge.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/queue.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/quickstart.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/reattribute.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/reattribute_cmd.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/recall.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/reconcile.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/reindex.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/retain.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/session_start.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/skill.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/status.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/stop_gate.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/trial.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/unmerge.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/verify.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/cli/why.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/client.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/distil/__init__.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/distil/candidates.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/distil/transcripts.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/eval/__init__.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/eval/backends/__init__.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/eval/backends/cognee.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/eval/backends/letta.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/eval/backends/mem0.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/eval/backends/registry.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/eval/backends/zep.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/eval/independent.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/eval/qa.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/eval/sweep.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/graph/__init__.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/graph/communities.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/infra/__init__.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/infra/config.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/infra/logging.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/infra/pool.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/infra/project.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/ingestion/__init__.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/ingestion/activity.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/ingestion/bootstrap.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/ingestion/capture.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/ingestion/resolution.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/env.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0001_initial_schema.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0002_trial_observations.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0003_project_and_agent_provenance.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0004_bootstrap_state.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0005_recall_save_guards.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0006_project_analysis.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0007_backfill_unknown_agent.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0008_read_events.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0009_read_event_attribution.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0010_stop_gate_fired.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0011_backfill_absent_agent.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0012_read_event_agent.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0013_active_fact_indexes.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0014_session_activity.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0015_retracted_observations.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0016_one_node_per_name.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0017_writer_version.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0018_trial_runs_are_history.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0019_versions_expected_since.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0020_who_closed_a_queued_document.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0021_delivery_evidence.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0022_independent_evaluation.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0023_second_judge.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0024_node_by_id.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0025_lexical_statistics.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0026_late_causal_extraction.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0027_lexical_staleness_without_a_scan.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0028_erasure_events.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0029_retention_policy.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/migrations/versions/0030_fact_attestation.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/retention.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/retrieval/__init__.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/retrieval/bm25.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/retrieval/causality.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/retrieval/fusion.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/retrieval/salience.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/server.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/skill/SKILL.md +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/trial/__init__.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/trial/check.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/trial/observations.py +0 -0
- {echo_mem-0.5.7 → echo_mem-0.6.0}/src/echo_memory/trial/reads.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: echo-mem
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.6.0
|
|
4
4
|
Summary: A long-horizon memory architecture for AI agents
|
|
5
5
|
License-Expression: Apache-2.0
|
|
6
6
|
Requires-Python: >=3.11
|
|
@@ -160,12 +160,37 @@ Answering for the data, which is the part a compliance review asks about:
|
|
|
160
160
|
echo-memory forget # erase facts outright, for a data subject's deletion request
|
|
161
161
|
echo-memory retain # how long this scope keeps a fact, and enforcing it
|
|
162
162
|
echo-memory verify # has any fact been changed behind this store's back
|
|
163
|
+
echo-memory exchange # signed, redacted knowledge bundles between organisations
|
|
164
|
+
echo-memory trust # record and read whether a fact was ever checked, and by whom
|
|
163
165
|
```
|
|
164
166
|
|
|
165
|
-
Those
|
|
167
|
+
Those five are deliberately not MCP tools, and a test reads the published
|
|
166
168
|
tool list so that adding one later fails. Irreversible deletion of a scope,
|
|
167
169
|
one prompt injection away from any agent holding a key, is not a trade worth
|
|
168
|
-
making.
|
|
170
|
+
making, and neither is handing one organisation's memory to another.
|
|
171
|
+
|
|
172
|
+
`trust` is the strongest of the five in one specific sense: it is the only
|
|
173
|
+
thing in this store that decides WHICH facts a read returns rather than the
|
|
174
|
+
order they come back in, so a tool for it would let any agent holding a key
|
|
175
|
+
mark its own claims `verified` and its inconvenient ones `rejected`.
|
|
176
|
+
|
|
177
|
+
Note that `trust` and `verify` are different jobs with confusingly close
|
|
178
|
+
names. `verify` asks whether the store has been tampered with, by checking the
|
|
179
|
+
attestation chain. `trust` records that a person checked a claim, which is what
|
|
180
|
+
`trust/states.py`'s six states are and what the lesson layer filters on.
|
|
181
|
+
`trust lessons` is also the only thing that explains an empty lesson list: it
|
|
182
|
+
prints which of the three bars was not cleared, because "no lessons" covers
|
|
183
|
+
both a scope whose outcomes disagree and a scope where nobody has verified
|
|
184
|
+
anything, and those have different owners.
|
|
185
|
+
|
|
186
|
+
`exchange` is one directional and there is no federation API. An export is a
|
|
187
|
+
signed file whose signature covers the redacted content, so what a recipient
|
|
188
|
+
verifies is what was actually sent. An import lands in a quarantine scope that
|
|
189
|
+
ordinary retrieval is not given, at `confidence: inferred`, and becomes
|
|
190
|
+
readable only when a named verifier promotes the bundle. Revoking one stops
|
|
191
|
+
the scope being readable from then on; it cannot recall facts already returned
|
|
192
|
+
into an agent's context, which is a property of having handed data over rather
|
|
193
|
+
than a gap, and `exchange export` says so before it writes anything.
|
|
169
194
|
|
|
170
195
|
### The seven MCP tools
|
|
171
196
|
|
|
@@ -322,6 +347,37 @@ instead of returning as though it had succeeded.
|
|
|
322
347
|
**Any MCP client.** A coding assistant, a chatbot, an ops agent, or something built in
|
|
323
348
|
house. Coding agents are where this is proven, not what it is limited to.
|
|
324
349
|
|
|
350
|
+
## Six capabilities on top of the graph
|
|
351
|
+
|
|
352
|
+
Machines reporting outcomes, a read across several memories, whether a claim was ever
|
|
353
|
+
checked, routing and a token budget for that read, signed bundles between organisations,
|
|
354
|
+
and the identity the hosted service binds a credential to. All of it is in the engine, so
|
|
355
|
+
self hosting gets all of it.
|
|
356
|
+
|
|
357
|
+
| | |
|
|
358
|
+
|---|---|
|
|
359
|
+
| **Collective learning** | A validated door for what CI runs, deploys and test suites report, a single writer behind it, and lessons derived at read time. A lesson is never stored: retire one supporting outcome and it stops being produced |
|
|
360
|
+
| **Knowledge networks** | `query_across` asks several scopes and fuses one ranked answer. With one scope the answer is byte identical to `query_memory` |
|
|
361
|
+
| **Agent identity** | A registry of the agents an account has, and runs recording what changed underneath one. Cloud only, because the engine has no concept of a principal |
|
|
362
|
+
| **Trust and verification** | Six states, append only, with their own tamper evident chain. Only `rejected` removes a fact from an answer, and only a verifier can set it. `echo-memory trust` is where a verifier sets one |
|
|
363
|
+
| **Context intelligence** | Which scopes are worth asking, decided with no model call, and an answer cut to a token budget that says what it dropped |
|
|
364
|
+
| **Knowledge exchange** | `echo-memory exchange`: a signed, redacted file. An import lands in a scope ordinary retrieval is never given until a verifier promotes it |
|
|
365
|
+
|
|
366
|
+
Two of these are off until an operator turns them on. `ECHO_MEMORY_TRUST_RETRIEVAL` and
|
|
367
|
+
`ECHO_MEMORY_LESSONS` default off, as does the graph wide write gate behind
|
|
368
|
+
`ECHO_MEMORY_MAX_GRAPH_WRITERS`, which costs 2.6x write throughput when on.
|
|
369
|
+
|
|
370
|
+
**What "in the engine" means, exactly.** Each of these is a Python API plus its tables,
|
|
371
|
+
and `echo-memory exchange` is the only one with a command. This release still registers
|
|
372
|
+
exactly 7 MCP tools, with the names and parameters 0.5.7 had, so nothing above reaches an
|
|
373
|
+
agent until something calls it: your own code, a future command, or the hosted service.
|
|
374
|
+
The event door in particular is an acceptance policy and an inbox, not a socket; a CI job
|
|
375
|
+
cannot post to the engine. `docs/INTELLIGENCE.md` names the entry point, or the absence of
|
|
376
|
+
one, per capability.
|
|
377
|
+
|
|
378
|
+
[`docs/INTELLIGENCE.md`](docs/INTELLIGENCE.md) is the guide: the API for each, what it
|
|
379
|
+
costs, every environment variable, and a section per capability on what it does not do.
|
|
380
|
+
|
|
325
381
|
## Numbers, and how they were taken
|
|
326
382
|
|
|
327
383
|
Every figure comes from this repository or a live store, with the command that reproduces
|
|
@@ -464,7 +520,7 @@ and the v1a to v1b plan.
|
|
|
464
520
|
|
|
465
521
|
| | |
|
|
466
522
|
|---|---|
|
|
467
|
-
| **v1a, built** | Basic recall. Seven MCP tools,
|
|
523
|
+
| **v1a, built** | Basic recall. Seven MCP tools, 40 CLI commands, on PyPI and in the MCP registry. |
|
|
468
524
|
| **v1b, part built** | Causal typing and `trace_cause` shipped in 0.5.0. Multi hop associative retrieval has not: 187 questions no single fact answers score MRR 0.212 today, and that number is what the rest of v1b has to beat. |
|
|
469
525
|
| **v1c, designed** | Consolidation: hot, consolidated and archived tiers, so retrieval cost stops tracking total facts written. Nothing implemented. |
|
|
470
526
|
| **v1.1, planned** | Organisation wide tenancy: per agent, per team, or org wide graphs. |
|
|
@@ -135,12 +135,37 @@ Answering for the data, which is the part a compliance review asks about:
|
|
|
135
135
|
echo-memory forget # erase facts outright, for a data subject's deletion request
|
|
136
136
|
echo-memory retain # how long this scope keeps a fact, and enforcing it
|
|
137
137
|
echo-memory verify # has any fact been changed behind this store's back
|
|
138
|
+
echo-memory exchange # signed, redacted knowledge bundles between organisations
|
|
139
|
+
echo-memory trust # record and read whether a fact was ever checked, and by whom
|
|
138
140
|
```
|
|
139
141
|
|
|
140
|
-
Those
|
|
142
|
+
Those five are deliberately not MCP tools, and a test reads the published
|
|
141
143
|
tool list so that adding one later fails. Irreversible deletion of a scope,
|
|
142
144
|
one prompt injection away from any agent holding a key, is not a trade worth
|
|
143
|
-
making.
|
|
145
|
+
making, and neither is handing one organisation's memory to another.
|
|
146
|
+
|
|
147
|
+
`trust` is the strongest of the five in one specific sense: it is the only
|
|
148
|
+
thing in this store that decides WHICH facts a read returns rather than the
|
|
149
|
+
order they come back in, so a tool for it would let any agent holding a key
|
|
150
|
+
mark its own claims `verified` and its inconvenient ones `rejected`.
|
|
151
|
+
|
|
152
|
+
Note that `trust` and `verify` are different jobs with confusingly close
|
|
153
|
+
names. `verify` asks whether the store has been tampered with, by checking the
|
|
154
|
+
attestation chain. `trust` records that a person checked a claim, which is what
|
|
155
|
+
`trust/states.py`'s six states are and what the lesson layer filters on.
|
|
156
|
+
`trust lessons` is also the only thing that explains an empty lesson list: it
|
|
157
|
+
prints which of the three bars was not cleared, because "no lessons" covers
|
|
158
|
+
both a scope whose outcomes disagree and a scope where nobody has verified
|
|
159
|
+
anything, and those have different owners.
|
|
160
|
+
|
|
161
|
+
`exchange` is one directional and there is no federation API. An export is a
|
|
162
|
+
signed file whose signature covers the redacted content, so what a recipient
|
|
163
|
+
verifies is what was actually sent. An import lands in a quarantine scope that
|
|
164
|
+
ordinary retrieval is not given, at `confidence: inferred`, and becomes
|
|
165
|
+
readable only when a named verifier promotes the bundle. Revoking one stops
|
|
166
|
+
the scope being readable from then on; it cannot recall facts already returned
|
|
167
|
+
into an agent's context, which is a property of having handed data over rather
|
|
168
|
+
than a gap, and `exchange export` says so before it writes anything.
|
|
144
169
|
|
|
145
170
|
### The seven MCP tools
|
|
146
171
|
|
|
@@ -297,6 +322,37 @@ instead of returning as though it had succeeded.
|
|
|
297
322
|
**Any MCP client.** A coding assistant, a chatbot, an ops agent, or something built in
|
|
298
323
|
house. Coding agents are where this is proven, not what it is limited to.
|
|
299
324
|
|
|
325
|
+
## Six capabilities on top of the graph
|
|
326
|
+
|
|
327
|
+
Machines reporting outcomes, a read across several memories, whether a claim was ever
|
|
328
|
+
checked, routing and a token budget for that read, signed bundles between organisations,
|
|
329
|
+
and the identity the hosted service binds a credential to. All of it is in the engine, so
|
|
330
|
+
self hosting gets all of it.
|
|
331
|
+
|
|
332
|
+
| | |
|
|
333
|
+
|---|---|
|
|
334
|
+
| **Collective learning** | A validated door for what CI runs, deploys and test suites report, a single writer behind it, and lessons derived at read time. A lesson is never stored: retire one supporting outcome and it stops being produced |
|
|
335
|
+
| **Knowledge networks** | `query_across` asks several scopes and fuses one ranked answer. With one scope the answer is byte identical to `query_memory` |
|
|
336
|
+
| **Agent identity** | A registry of the agents an account has, and runs recording what changed underneath one. Cloud only, because the engine has no concept of a principal |
|
|
337
|
+
| **Trust and verification** | Six states, append only, with their own tamper evident chain. Only `rejected` removes a fact from an answer, and only a verifier can set it. `echo-memory trust` is where a verifier sets one |
|
|
338
|
+
| **Context intelligence** | Which scopes are worth asking, decided with no model call, and an answer cut to a token budget that says what it dropped |
|
|
339
|
+
| **Knowledge exchange** | `echo-memory exchange`: a signed, redacted file. An import lands in a scope ordinary retrieval is never given until a verifier promotes it |
|
|
340
|
+
|
|
341
|
+
Two of these are off until an operator turns them on. `ECHO_MEMORY_TRUST_RETRIEVAL` and
|
|
342
|
+
`ECHO_MEMORY_LESSONS` default off, as does the graph wide write gate behind
|
|
343
|
+
`ECHO_MEMORY_MAX_GRAPH_WRITERS`, which costs 2.6x write throughput when on.
|
|
344
|
+
|
|
345
|
+
**What "in the engine" means, exactly.** Each of these is a Python API plus its tables,
|
|
346
|
+
and `echo-memory exchange` is the only one with a command. This release still registers
|
|
347
|
+
exactly 7 MCP tools, with the names and parameters 0.5.7 had, so nothing above reaches an
|
|
348
|
+
agent until something calls it: your own code, a future command, or the hosted service.
|
|
349
|
+
The event door in particular is an acceptance policy and an inbox, not a socket; a CI job
|
|
350
|
+
cannot post to the engine. `docs/INTELLIGENCE.md` names the entry point, or the absence of
|
|
351
|
+
one, per capability.
|
|
352
|
+
|
|
353
|
+
[`docs/INTELLIGENCE.md`](docs/INTELLIGENCE.md) is the guide: the API for each, what it
|
|
354
|
+
costs, every environment variable, and a section per capability on what it does not do.
|
|
355
|
+
|
|
300
356
|
## Numbers, and how they were taken
|
|
301
357
|
|
|
302
358
|
Every figure comes from this repository or a live store, with the command that reproduces
|
|
@@ -439,7 +495,7 @@ and the v1a to v1b plan.
|
|
|
439
495
|
|
|
440
496
|
| | |
|
|
441
497
|
|---|---|
|
|
442
|
-
| **v1a, built** | Basic recall. Seven MCP tools,
|
|
498
|
+
| **v1a, built** | Basic recall. Seven MCP tools, 40 CLI commands, on PyPI and in the MCP registry. |
|
|
443
499
|
| **v1b, part built** | Causal typing and `trace_cause` shipped in 0.5.0. Multi hop associative retrieval has not: 187 questions no single fact answers score MRR 0.212 today, and that number is what the rest of v1b has to beat. |
|
|
444
500
|
| **v1c, designed** | Consolidation: hot, consolidated and archived tiers, so retrieval cost stops tracking total facts written. Nothing implemented. |
|
|
445
501
|
| **v1.1, planned** | Organisation wide tenancy: per agent, per team, or org wide graphs. |
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
# (`-m echo_memory.server`) and every existing install reference it, and
|
|
7
7
|
# renaming the module would break live configuration to fix a cosmetic mismatch.
|
|
8
8
|
name = "echo-mem"
|
|
9
|
-
version = "0.
|
|
9
|
+
version = "0.6.0"
|
|
10
10
|
description = "A long-horizon memory architecture for AI agents"
|
|
11
11
|
readme = "README.md"
|
|
12
12
|
# An SPDX expression, not an inlined licence text: pip, PyPI and every
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: echo-mem
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.6.0
|
|
4
4
|
Summary: A long-horizon memory architecture for AI agents
|
|
5
5
|
License-Expression: Apache-2.0
|
|
6
6
|
Requires-Python: >=3.11
|
|
@@ -160,12 +160,37 @@ Answering for the data, which is the part a compliance review asks about:
|
|
|
160
160
|
echo-memory forget # erase facts outright, for a data subject's deletion request
|
|
161
161
|
echo-memory retain # how long this scope keeps a fact, and enforcing it
|
|
162
162
|
echo-memory verify # has any fact been changed behind this store's back
|
|
163
|
+
echo-memory exchange # signed, redacted knowledge bundles between organisations
|
|
164
|
+
echo-memory trust # record and read whether a fact was ever checked, and by whom
|
|
163
165
|
```
|
|
164
166
|
|
|
165
|
-
Those
|
|
167
|
+
Those five are deliberately not MCP tools, and a test reads the published
|
|
166
168
|
tool list so that adding one later fails. Irreversible deletion of a scope,
|
|
167
169
|
one prompt injection away from any agent holding a key, is not a trade worth
|
|
168
|
-
making.
|
|
170
|
+
making, and neither is handing one organisation's memory to another.
|
|
171
|
+
|
|
172
|
+
`trust` is the strongest of the five in one specific sense: it is the only
|
|
173
|
+
thing in this store that decides WHICH facts a read returns rather than the
|
|
174
|
+
order they come back in, so a tool for it would let any agent holding a key
|
|
175
|
+
mark its own claims `verified` and its inconvenient ones `rejected`.
|
|
176
|
+
|
|
177
|
+
Note that `trust` and `verify` are different jobs with confusingly close
|
|
178
|
+
names. `verify` asks whether the store has been tampered with, by checking the
|
|
179
|
+
attestation chain. `trust` records that a person checked a claim, which is what
|
|
180
|
+
`trust/states.py`'s six states are and what the lesson layer filters on.
|
|
181
|
+
`trust lessons` is also the only thing that explains an empty lesson list: it
|
|
182
|
+
prints which of the three bars was not cleared, because "no lessons" covers
|
|
183
|
+
both a scope whose outcomes disagree and a scope where nobody has verified
|
|
184
|
+
anything, and those have different owners.
|
|
185
|
+
|
|
186
|
+
`exchange` is one directional and there is no federation API. An export is a
|
|
187
|
+
signed file whose signature covers the redacted content, so what a recipient
|
|
188
|
+
verifies is what was actually sent. An import lands in a quarantine scope that
|
|
189
|
+
ordinary retrieval is not given, at `confidence: inferred`, and becomes
|
|
190
|
+
readable only when a named verifier promotes the bundle. Revoking one stops
|
|
191
|
+
the scope being readable from then on; it cannot recall facts already returned
|
|
192
|
+
into an agent's context, which is a property of having handed data over rather
|
|
193
|
+
than a gap, and `exchange export` says so before it writes anything.
|
|
169
194
|
|
|
170
195
|
### The seven MCP tools
|
|
171
196
|
|
|
@@ -322,6 +347,37 @@ instead of returning as though it had succeeded.
|
|
|
322
347
|
**Any MCP client.** A coding assistant, a chatbot, an ops agent, or something built in
|
|
323
348
|
house. Coding agents are where this is proven, not what it is limited to.
|
|
324
349
|
|
|
350
|
+
## Six capabilities on top of the graph
|
|
351
|
+
|
|
352
|
+
Machines reporting outcomes, a read across several memories, whether a claim was ever
|
|
353
|
+
checked, routing and a token budget for that read, signed bundles between organisations,
|
|
354
|
+
and the identity the hosted service binds a credential to. All of it is in the engine, so
|
|
355
|
+
self hosting gets all of it.
|
|
356
|
+
|
|
357
|
+
| | |
|
|
358
|
+
|---|---|
|
|
359
|
+
| **Collective learning** | A validated door for what CI runs, deploys and test suites report, a single writer behind it, and lessons derived at read time. A lesson is never stored: retire one supporting outcome and it stops being produced |
|
|
360
|
+
| **Knowledge networks** | `query_across` asks several scopes and fuses one ranked answer. With one scope the answer is byte identical to `query_memory` |
|
|
361
|
+
| **Agent identity** | A registry of the agents an account has, and runs recording what changed underneath one. Cloud only, because the engine has no concept of a principal |
|
|
362
|
+
| **Trust and verification** | Six states, append only, with their own tamper evident chain. Only `rejected` removes a fact from an answer, and only a verifier can set it. `echo-memory trust` is where a verifier sets one |
|
|
363
|
+
| **Context intelligence** | Which scopes are worth asking, decided with no model call, and an answer cut to a token budget that says what it dropped |
|
|
364
|
+
| **Knowledge exchange** | `echo-memory exchange`: a signed, redacted file. An import lands in a scope ordinary retrieval is never given until a verifier promotes it |
|
|
365
|
+
|
|
366
|
+
Two of these are off until an operator turns them on. `ECHO_MEMORY_TRUST_RETRIEVAL` and
|
|
367
|
+
`ECHO_MEMORY_LESSONS` default off, as does the graph wide write gate behind
|
|
368
|
+
`ECHO_MEMORY_MAX_GRAPH_WRITERS`, which costs 2.6x write throughput when on.
|
|
369
|
+
|
|
370
|
+
**What "in the engine" means, exactly.** Each of these is a Python API plus its tables,
|
|
371
|
+
and `echo-memory exchange` is the only one with a command. This release still registers
|
|
372
|
+
exactly 7 MCP tools, with the names and parameters 0.5.7 had, so nothing above reaches an
|
|
373
|
+
agent until something calls it: your own code, a future command, or the hosted service.
|
|
374
|
+
The event door in particular is an acceptance policy and an inbox, not a socket; a CI job
|
|
375
|
+
cannot post to the engine. `docs/INTELLIGENCE.md` names the entry point, or the absence of
|
|
376
|
+
one, per capability.
|
|
377
|
+
|
|
378
|
+
[`docs/INTELLIGENCE.md`](docs/INTELLIGENCE.md) is the guide: the API for each, what it
|
|
379
|
+
costs, every environment variable, and a section per capability on what it does not do.
|
|
380
|
+
|
|
325
381
|
## Numbers, and how they were taken
|
|
326
382
|
|
|
327
383
|
Every figure comes from this repository or a live store, with the command that reproduces
|
|
@@ -464,7 +520,7 @@ and the v1a to v1b plan.
|
|
|
464
520
|
|
|
465
521
|
| | |
|
|
466
522
|
|---|---|
|
|
467
|
-
| **v1a, built** | Basic recall. Seven MCP tools,
|
|
523
|
+
| **v1a, built** | Basic recall. Seven MCP tools, 40 CLI commands, on PyPI and in the MCP registry. |
|
|
468
524
|
| **v1b, part built** | Causal typing and `trace_cause` shipped in 0.5.0. Multi hop associative retrieval has not: 187 questions no single fact answers score MRR 0.212 today, and that number is what the rest of v1b has to beat. |
|
|
469
525
|
| **v1c, designed** | Consolidation: hot, consolidated and archived tiers, so retrieval cost stops tracking total facts written. Nothing implemented. |
|
|
470
526
|
| **v1.1, planned** | Organisation wide tenancy: per agent, per team, or org wide graphs. |
|
|
@@ -25,6 +25,7 @@ src/echo_memory/cli/connect.py
|
|
|
25
25
|
src/echo_memory/cli/dashboard.py
|
|
26
26
|
src/echo_memory/cli/dashboard_html.py
|
|
27
27
|
src/echo_memory/cli/distil.py
|
|
28
|
+
src/echo_memory/cli/exchange.py
|
|
28
29
|
src/echo_memory/cli/export.py
|
|
29
30
|
src/echo_memory/cli/forget.py
|
|
30
31
|
src/echo_memory/cli/graph.py
|
|
@@ -50,6 +51,7 @@ src/echo_memory/cli/skill.py
|
|
|
50
51
|
src/echo_memory/cli/status.py
|
|
51
52
|
src/echo_memory/cli/stop_gate.py
|
|
52
53
|
src/echo_memory/cli/trial.py
|
|
54
|
+
src/echo_memory/cli/trust.py
|
|
53
55
|
src/echo_memory/cli/unmerge.py
|
|
54
56
|
src/echo_memory/cli/verify.py
|
|
55
57
|
src/echo_memory/cli/why.py
|
|
@@ -61,6 +63,7 @@ src/echo_memory/eval/external.py
|
|
|
61
63
|
src/echo_memory/eval/independent.py
|
|
62
64
|
src/echo_memory/eval/qa.py
|
|
63
65
|
src/echo_memory/eval/retrieval.py
|
|
66
|
+
src/echo_memory/eval/scratchpad_eval.py
|
|
64
67
|
src/echo_memory/eval/sweep.py
|
|
65
68
|
src/echo_memory/eval/backends/__init__.py
|
|
66
69
|
src/echo_memory/eval/backends/cognee.py
|
|
@@ -69,14 +72,26 @@ src/echo_memory/eval/backends/letta.py
|
|
|
69
72
|
src/echo_memory/eval/backends/mem0.py
|
|
70
73
|
src/echo_memory/eval/backends/registry.py
|
|
71
74
|
src/echo_memory/eval/backends/zep.py
|
|
75
|
+
src/echo_memory/events/__init__.py
|
|
76
|
+
src/echo_memory/events/envelope.py
|
|
77
|
+
src/echo_memory/events/inbox.py
|
|
78
|
+
src/echo_memory/exchange/__init__.py
|
|
79
|
+
src/echo_memory/exchange/bundle.py
|
|
80
|
+
src/echo_memory/exchange/importer.py
|
|
81
|
+
src/echo_memory/exchange/redact.py
|
|
82
|
+
src/echo_memory/exchange/sign.py
|
|
72
83
|
src/echo_memory/graph/__init__.py
|
|
73
84
|
src/echo_memory/graph/communities.py
|
|
74
85
|
src/echo_memory/infra/__init__.py
|
|
75
86
|
src/echo_memory/infra/config.py
|
|
76
87
|
src/echo_memory/infra/db.py
|
|
88
|
+
src/echo_memory/infra/graph_gate.py
|
|
89
|
+
src/echo_memory/infra/graphlock.py
|
|
77
90
|
src/echo_memory/infra/logging.py
|
|
91
|
+
src/echo_memory/infra/metrics.py
|
|
78
92
|
src/echo_memory/infra/pool.py
|
|
79
93
|
src/echo_memory/infra/project.py
|
|
94
|
+
src/echo_memory/infra/provider.py
|
|
80
95
|
src/echo_memory/ingestion/__init__.py
|
|
81
96
|
src/echo_memory/ingestion/activity.py
|
|
82
97
|
src/echo_memory/ingestion/bootstrap.py
|
|
@@ -85,6 +100,11 @@ src/echo_memory/ingestion/embeddings.py
|
|
|
85
100
|
src/echo_memory/ingestion/neighbourhood.py
|
|
86
101
|
src/echo_memory/ingestion/resolution.py
|
|
87
102
|
src/echo_memory/ingestion/write_episode.py
|
|
103
|
+
src/echo_memory/intelligence/__init__.py
|
|
104
|
+
src/echo_memory/intelligence/lessons.py
|
|
105
|
+
src/echo_memory/intelligence/naming.py
|
|
106
|
+
src/echo_memory/intelligence/outcomes.py
|
|
107
|
+
src/echo_memory/intelligence/vocabulary.py
|
|
88
108
|
src/echo_memory/migrations/env.py
|
|
89
109
|
src/echo_memory/migrations/versions/0001_initial_schema.py
|
|
90
110
|
src/echo_memory/migrations/versions/0002_trial_observations.py
|
|
@@ -116,14 +136,32 @@ src/echo_memory/migrations/versions/0027_lexical_staleness_without_a_scan.py
|
|
|
116
136
|
src/echo_memory/migrations/versions/0028_erasure_events.py
|
|
117
137
|
src/echo_memory/migrations/versions/0029_retention_policy.py
|
|
118
138
|
src/echo_memory/migrations/versions/0030_fact_attestation.py
|
|
139
|
+
src/echo_memory/migrations/versions/0031_evidence.py
|
|
140
|
+
src/echo_memory/migrations/versions/0032_fact_verification.py
|
|
141
|
+
src/echo_memory/migrations/versions/0033_event_inbox.py
|
|
142
|
+
src/echo_memory/migrations/versions/0034_decision_vocabulary.py
|
|
143
|
+
src/echo_memory/migrations/versions/0035_bundle_registry.py
|
|
144
|
+
src/echo_memory/migrations/versions/0036_hardening_indexes.py
|
|
145
|
+
src/echo_memory/migrations/versions/0037_event_inbox_scoped_key.py
|
|
146
|
+
src/echo_memory/migrations/versions/0038_bundle_registry_scoped_key.py
|
|
119
147
|
src/echo_memory/retrieval/__init__.py
|
|
148
|
+
src/echo_memory/retrieval/across.py
|
|
120
149
|
src/echo_memory/retrieval/bm25.py
|
|
121
150
|
src/echo_memory/retrieval/causality.py
|
|
151
|
+
src/echo_memory/retrieval/context.py
|
|
152
|
+
src/echo_memory/retrieval/envelope.py
|
|
122
153
|
src/echo_memory/retrieval/fusion.py
|
|
123
154
|
src/echo_memory/retrieval/query_memory.py
|
|
155
|
+
src/echo_memory/retrieval/routing.py
|
|
124
156
|
src/echo_memory/retrieval/salience.py
|
|
157
|
+
src/echo_memory/retrieval/scratchpad.py
|
|
125
158
|
src/echo_memory/skill/SKILL.md
|
|
126
159
|
src/echo_memory/trial/__init__.py
|
|
127
160
|
src/echo_memory/trial/check.py
|
|
128
161
|
src/echo_memory/trial/observations.py
|
|
129
|
-
src/echo_memory/trial/reads.py
|
|
162
|
+
src/echo_memory/trial/reads.py
|
|
163
|
+
src/echo_memory/trust/__init__.py
|
|
164
|
+
src/echo_memory/trust/evidence.py
|
|
165
|
+
src/echo_memory/trust/states.py
|
|
166
|
+
src/echo_memory/trust/vattest.py
|
|
167
|
+
src/echo_memory/trust/verify.py
|
|
@@ -147,44 +147,105 @@ def _value(raw):
|
|
|
147
147
|
return json.loads(str(raw))
|
|
148
148
|
|
|
149
149
|
|
|
150
|
+
def _decoded(raw):
|
|
151
|
+
"""One agtype property as read by `->>`, which hands back raw text.
|
|
152
|
+
|
|
153
|
+
The counterpart to `_value`, and they must agree. `_value` decodes the
|
|
154
|
+
JSON quoted form Cypher returns; this one has the decoded text already and
|
|
155
|
+
only has to turn agtype's `null` into Python's. An absent property comes
|
|
156
|
+
back as SQL NULL here and as the agtype `null` through Cypher, and a digest
|
|
157
|
+
that told those apart would depend on which reader saw the fact.
|
|
158
|
+
"""
|
|
159
|
+
if raw is None or str(raw) == "null":
|
|
160
|
+
return None
|
|
161
|
+
return str(raw)
|
|
162
|
+
|
|
163
|
+
|
|
150
164
|
def claims_of(conn, group_id: str, edge_id: str) -> dict:
|
|
151
165
|
"""What a fact says about itself, read back from the graph.
|
|
152
166
|
|
|
153
167
|
Includes the endpoint names, because moving an edge from one node to
|
|
154
|
-
another changes its meaning entirely
|
|
155
|
-
"billing uses Stripe"
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
168
|
+
another changes its meaning entirely: "billing uses Razorpay" becomes
|
|
169
|
+
"billing uses Stripe" without touching a single covered property.
|
|
170
|
+
|
|
171
|
+
## Why this reads the tables and not Cypher
|
|
172
|
+
|
|
173
|
+
It used to ask through Cypher, and the comment then said the per-property
|
|
174
|
+
projection was "the only form that works on both a map and a scalar". That
|
|
175
|
+
was half right. `properties::text` on a map is indeed refused, but a
|
|
176
|
+
NESTED projection is not: `properties -> '"provenance"' ->> '"session_id"'`
|
|
177
|
+
reaches inside the map and returns the one value this function wants.
|
|
178
|
+
|
|
179
|
+
The cost of asking through Cypher was that `MATCH (a)-[e:FACT]->(b) WHERE
|
|
180
|
+
id(e) = $eid` leaves the pattern unbound, so AGE expands every FACT edge in
|
|
181
|
+
the graph before filtering by id. On the write path, once per fact written.
|
|
182
|
+
Measured on this schema, one fact read by id out of a growing graph:
|
|
183
|
+
|
|
184
|
+
edges in graph through Cypher off the tables speedup
|
|
185
|
+
307 0.776 ms 0.409 ms 1.9x
|
|
186
|
+
1,807 2.339 ms 0.657 ms 3.6x
|
|
187
|
+
5,807 6.785 ms 0.694 ms 9.8x
|
|
188
|
+
|
|
189
|
+
Cypher grows linearly and the table read does not, which is the signature
|
|
190
|
+
of a sequential scan against an index scan. It is the same defect already
|
|
191
|
+
fixed twice in `neighbourhood._adjacent` and once in `_graph_candidates`,
|
|
192
|
+
and migration 0024 describes the shape: "write cost rose from 29ms at
|
|
193
|
+
1,057 nodes to 129ms at 24,054... read as the corpus being large rather
|
|
194
|
+
than as a defect".
|
|
195
|
+
|
|
196
|
+
## Why moving it was dangerous, and what was proven first
|
|
197
|
+
|
|
198
|
+
This function feeds `canonical()`, which feeds the digest. The two reads do
|
|
199
|
+
NOT return the same bytes: Cypher returns JSON quoted agtype (`'"uses"'`)
|
|
200
|
+
and `->>` returns raw text (`'uses'`). Measured across seven facts chosen
|
|
201
|
+
to break a naive decoder - embedded newline, embedded quotes, a backslash
|
|
202
|
+
path, unicode, text that looks like a JSON object, a tab, and one fact with
|
|
203
|
+
no causal_hint at all - 51 of 63 fields differed in their raw form.
|
|
204
|
+
|
|
205
|
+
What was proven before the change landed is that they agree once DECODED:
|
|
206
|
+
raw text equals `json.loads(quoted)` for all 63, with `t_valid` needing an
|
|
207
|
+
int cast because `->>` hands back a string. So `_value` stays for the
|
|
208
|
+
Cypher form, `_decoded` is its counterpart here, and the digest over every
|
|
209
|
+
covered property is unchanged. `tests/integration/test_attestation.py`
|
|
210
|
+
pins that with a populated store: same claims, same digests, same head,
|
|
211
|
+
clean report.
|
|
212
|
+
|
|
213
|
+
If a future change touches either reader, that equivalence is the thing to
|
|
214
|
+
re-prove. Getting it wrong does not fail a test loudly; it reports every
|
|
215
|
+
fact in every store as altered.
|
|
160
216
|
"""
|
|
217
|
+
props = ", ".join(
|
|
218
|
+
f'''(e.properties ->> '"{key}"'::agtype)''' for key in COVERED
|
|
219
|
+
)
|
|
161
220
|
row = conn.execute(
|
|
162
|
-
f"""SELECT
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
(
|
|
221
|
+
f"""SELECT (a.properties ->> '"name"'::agtype),
|
|
222
|
+
(b.properties ->> '"name"'::agtype),
|
|
223
|
+
{props},
|
|
224
|
+
((e.properties -> '"provenance"'::agtype)
|
|
225
|
+
->> '"session_id"'::agtype)
|
|
226
|
+
FROM {GRAPH}."FACT" e
|
|
227
|
+
JOIN {GRAPH}."Node" a ON a.id = e.start_id
|
|
228
|
+
JOIN {GRAPH}."Node" b ON b.id = e.end_id
|
|
229
|
+
WHERE e.id = %s::graphid
|
|
230
|
+
AND {_GROUP.replace("properties", "e.properties")} = %s""",
|
|
231
|
+
(str(edge_id), group_id),
|
|
173
232
|
).fetchone()
|
|
174
233
|
if row is None:
|
|
175
234
|
raise AttestationError(f"no fact {edge_id} in {group_id}")
|
|
176
235
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
236
|
+
source, target = _decoded(row[0]), _decoded(row[1])
|
|
237
|
+
covered = dict(zip(COVERED, (_decoded(v) for v in row[2:-1]), strict=True))
|
|
238
|
+
# t_valid is a number in the digest and a string out of ->>. Cast rather
|
|
239
|
+
# than left as text: a digest over "1762800000" is not a digest over
|
|
240
|
+
# 1762800000, and the whole point of this change is that it is.
|
|
241
|
+
if covered.get("t_valid") is not None:
|
|
242
|
+
covered["t_valid"] = int(covered["t_valid"])
|
|
181
243
|
return {
|
|
182
244
|
"group_id": group_id,
|
|
183
245
|
"source": source,
|
|
184
246
|
"target": target,
|
|
185
247
|
**covered,
|
|
186
|
-
"session_id":
|
|
187
|
-
if isinstance(provenance, dict) else None,
|
|
248
|
+
"session_id": _decoded(row[-1]),
|
|
188
249
|
}
|
|
189
250
|
|
|
190
251
|
|