echo-mem 0.5.4__tar.gz → 0.5.6__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.6/NOTICE +10 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/PKG-INFO +93 -45
- echo_mem-0.5.4/src/echo_mem.egg-info/PKG-INFO → echo_mem-0.5.6/README.md +87 -62
- {echo_mem-0.5.4 → echo_mem-0.5.6}/pyproject.toml +11 -12
- echo_mem-0.5.4/README.md → echo_mem-0.5.6/src/echo_mem.egg-info/PKG-INFO +110 -39
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_mem.egg-info/SOURCES.txt +8 -1
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_mem.egg-info/requires.txt +3 -3
- echo_mem-0.5.6/src/echo_memory/cli/distil.py +128 -0
- echo_mem-0.5.6/src/echo_memory/cli/forget.py +148 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/main.py +71 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/recall.py +20 -2
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/client.py +4 -1
- echo_mem-0.5.6/src/echo_memory/distil/__init__.py +15 -0
- echo_mem-0.5.6/src/echo_memory/distil/candidates.py +195 -0
- echo_mem-0.5.6/src/echo_memory/distil/transcripts.py +183 -0
- echo_mem-0.5.6/src/echo_memory/erasure.py +531 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/eval/independent.py +2 -2
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/infra/logging.py +13 -1
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/ingestion/write_episode.py +117 -15
- echo_mem-0.5.6/src/echo_memory/migrations/versions/0028_erasure_events.py +92 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/retrieval/query_memory.py +13 -1
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/server.py +18 -10
- echo_mem-0.5.4/LICENSE +0 -96
- /echo_mem-0.5.4/LICENSE-APACHE-2.0 → /echo_mem-0.5.6/LICENSE +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/setup.cfg +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_mem.egg-info/dependency_links.txt +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_mem.egg-info/entry_points.txt +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_mem.egg-info/top_level.txt +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/__init__.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/audit/__init__.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/audit/get_audit_log.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/__init__.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/adopt.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/analyse.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/benchmark.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/calibrate.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/connect.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/dashboard.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/dashboard_html.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/export.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/graph.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/health.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/hooks.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/infer_causal.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/initdb.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/install.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/judge.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/llm.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/merge.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/queue.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/quickstart.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/reattribute.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/reattribute_cmd.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/reconcile.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/reindex.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/session_start.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/skill.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/status.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/stop_gate.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/trial.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/unmerge.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/why.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/eval/__init__.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/eval/external.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/eval/retrieval.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/eval/sweep.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/graph/__init__.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/graph/communities.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/infra/__init__.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/infra/config.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/infra/db.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/infra/pool.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/infra/project.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/ingestion/__init__.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/ingestion/activity.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/ingestion/bootstrap.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/ingestion/capture.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/ingestion/embeddings.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/ingestion/neighbourhood.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/ingestion/resolution.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/env.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0001_initial_schema.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0002_trial_observations.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0003_project_and_agent_provenance.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0004_bootstrap_state.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0005_recall_save_guards.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0006_project_analysis.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0007_backfill_unknown_agent.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0008_read_events.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0009_read_event_attribution.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0010_stop_gate_fired.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0011_backfill_absent_agent.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0012_read_event_agent.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0013_active_fact_indexes.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0014_session_activity.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0015_retracted_observations.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0016_one_node_per_name.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0017_writer_version.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0018_trial_runs_are_history.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0019_versions_expected_since.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0020_who_closed_a_queued_document.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0021_delivery_evidence.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0022_independent_evaluation.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0023_second_judge.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0024_node_by_id.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0025_lexical_statistics.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0026_late_causal_extraction.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0027_lexical_staleness_without_a_scan.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/retrieval/__init__.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/retrieval/bm25.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/retrieval/causality.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/retrieval/fusion.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/retrieval/salience.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/skill/SKILL.md +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/trial/__init__.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/trial/check.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/trial/observations.py +0 -0
- {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/trial/reads.py +0 -0
echo_mem-0.5.6/NOTICE
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
Echo Memory
|
|
2
|
+
Copyright 2026 Ateleir Tech
|
|
3
|
+
|
|
4
|
+
Licensed under the Apache License, Version 2.0. See LICENSE.
|
|
5
|
+
|
|
6
|
+
Versions 0.5.0 through 0.5.5 were published under the Business Source License
|
|
7
|
+
1.1 between 25 September and 26 October 2026. Ateleir Tech holds the copyright
|
|
8
|
+
in the whole work and relicenses all of it, including those versions, under
|
|
9
|
+
Apache 2.0. Nobody who obtained a copy under either licence loses any right
|
|
10
|
+
they already had: this grant is strictly wider than the one it replaces.
|
|
@@ -1,24 +1,24 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: echo-mem
|
|
3
|
-
Version: 0.5.
|
|
3
|
+
Version: 0.5.6
|
|
4
4
|
Summary: A long-horizon memory architecture for AI agents
|
|
5
|
-
License-Expression:
|
|
5
|
+
License-Expression: Apache-2.0
|
|
6
6
|
Requires-Python: >=3.11
|
|
7
7
|
Description-Content-Type: text/markdown
|
|
8
8
|
License-File: LICENSE
|
|
9
|
-
License-File:
|
|
9
|
+
License-File: NOTICE
|
|
10
10
|
Requires-Dist: psycopg[binary]<4,>=3.2
|
|
11
11
|
Requires-Dist: psycopg-pool<4,>=3.2
|
|
12
12
|
Requires-Dist: pgvector<1,>=0.3
|
|
13
13
|
Requires-Dist: alembic<2,>=1.13
|
|
14
14
|
Requires-Dist: sqlalchemy<3,>=2
|
|
15
15
|
Requires-Dist: mcp<3,>=2.0
|
|
16
|
-
Requires-Dist: sentence-transformers<
|
|
16
|
+
Requires-Dist: sentence-transformers<7,>=3
|
|
17
17
|
Provides-Extra: dev
|
|
18
|
-
Requires-Dist: pytest<
|
|
18
|
+
Requires-Dist: pytest<10,>=8; extra == "dev"
|
|
19
19
|
Requires-Dist: ruff<1,>=0.6; extra == "dev"
|
|
20
20
|
Requires-Dist: build<2,>=1; extra == "dev"
|
|
21
|
-
Requires-Dist: twine<
|
|
21
|
+
Requires-Dist: twine<8,>=5; extra == "dev"
|
|
22
22
|
Dynamic: license-file
|
|
23
23
|
|
|
24
24
|
# Echo Memory
|
|
@@ -26,17 +26,24 @@ Dynamic: license-file
|
|
|
26
26
|
[](https://github.com/echo-mem/echo-mem/actions/workflows/ci.yml)
|
|
27
27
|
[](https://pypi.org/project/echo-mem/)
|
|
28
28
|
[](https://pypi.org/project/echo-mem/)
|
|
29
|
-
[](LICENSE)
|
|
30
30
|
|
|
31
31
|
**Shared memory for AI agents, as a graph in your own database.** What Claude Code learns,
|
|
32
32
|
Cursor and Codex can recall. Every fact records who wrote it and when, and the server
|
|
33
33
|
never calls a model to store one.
|
|
34
34
|
|
|
35
|
+

|
|
36
|
+
|
|
37
|
+
<sub>Every line above is real output, captured from these commands against a throwaway
|
|
38
|
+
database. The transcript is at
|
|
39
|
+
[`.github/branding/demo-transcript.txt`](.github/branding/demo-transcript.txt).</sub>
|
|
40
|
+
|
|
35
41
|
> Your agents start every session from zero. The usual fix is a notes file you paste into
|
|
36
42
|
> context, which grows until it is mostly irrelevant to whatever you are asking. Echo
|
|
37
43
|
> Memory is the other shape: facts connected to each other, and a query that returns the
|
|
38
|
-
> few that matter. On the author's own store that is **96.7% less context** for
|
|
39
|
-
> answer, with the answer still present 87.2% of the time across 1,190
|
|
44
|
+
> few that matter. On the author's own 325 fact store that is **96.7% less context** for
|
|
45
|
+
> the same answer, with the answer still present 87.2% of the time across 1,190 queries
|
|
46
|
+
> the harness derived from their own answers.
|
|
40
47
|
|
|
41
48
|
```
|
|
42
49
|
write_episode query_memory
|
|
@@ -199,10 +206,34 @@ could not answer the first question a post mortem asks. `query_memory` takes `as
|
|
|
199
206
|
unix seconds and every channel honours it: vector, full text, the graph hop, the digest.
|
|
200
207
|
|
|
201
208
|
Supersession is what makes that more than a curiosity. Writing the same source, target and
|
|
202
|
-
relation again does not edit the old fact, it ends it: the old
|
|
203
|
-
stays queryable. Nothing is ever rewritten, so the history is
|
|
204
|
-
reconstructed, which is the property the memory reconsolidation
|
|
205
|
-
the reason this project refuses that idea.
|
|
209
|
+
relation again with a **changed** claim does not edit the old fact, it ends it: the old
|
|
210
|
+
edge takes a `t_invalid` and stays queryable. Nothing is ever rewritten, so the history is
|
|
211
|
+
real rather than reconstructed, which is the property the memory reconsolidation
|
|
212
|
+
literature gives up and the reason this project refuses that idea.
|
|
213
|
+
|
|
214
|
+
Restating an **unchanged** claim is not a change and no longer counts as one. If the fact
|
|
215
|
+
text, the confidence and the causal hint all match the edge already there, the write is
|
|
216
|
+
skipped and reported under `restated`. It used to create a second edge, end the first, and
|
|
217
|
+
emit a supersession whose `before_fact` equalled its `after_fact`. That is the mechanism
|
|
218
|
+
behind one customer edge carrying 47 versions of a single sentence, and behind 543 writes
|
|
219
|
+
producing 112 facts while every one of them was billed. It also makes a retry safe: with
|
|
220
|
+
no idempotency key, a caller retrying a write that had actually landed used to burn a
|
|
221
|
+
version on it.
|
|
222
|
+
|
|
223
|
+
**Every write answers whether it stored anything.** `write_episode` can end with an empty
|
|
224
|
+
`edges_created` four different ways, and from the caller's side they used to be
|
|
225
|
+
indistinguishable without knowing which other key to inspect. Each one now reports
|
|
226
|
+
`stored: false` and names itself in `not_stored`: `refused` (validation rejected it),
|
|
227
|
+
`deferred` (an entity mention was close enough to an existing node to be worth asking
|
|
228
|
+
about and not close enough to merge), `unchanged` (every fact already existed word for
|
|
229
|
+
word) and `no_facts` (the episode asserted none). A refusal carries the same keys as a
|
|
230
|
+
success, so one check works on every path, and `retryable` separates a database blip worth
|
|
231
|
+
retrying from a validation error that will fail forever. A write that stored some of its
|
|
232
|
+
facts and held the rest says `partial`.
|
|
233
|
+
|
|
234
|
+
The deferral is the one that cost real data, because it looks most like success: a well
|
|
235
|
+
formed response, no error, `isError` false, and nothing written. A customer loading 26,633
|
|
236
|
+
facts read that as 26,633 successes and stored 1,650.
|
|
206
237
|
|
|
207
238
|
**Provenance on every fact.** Who wrote it, which tool, which project, when, and which
|
|
208
239
|
reads returned it. A superseded fact is never deleted. It stops being drawn and stays
|
|
@@ -248,27 +279,34 @@ Zep/Graphiti, the closest architectural match, whose own description of ingestio
|
|
|
248
279
|
The obvious reply is that cheap writes are cheap because they do less, and that reply is
|
|
249
280
|
correct on the mechanism. [`docs/WRITE-COST.md`](docs/WRITE-COST.md) answers it properly,
|
|
250
281
|
including the two measured costs of the choice: the Stop gate fired seven times and
|
|
251
|
-
produced one fact, and a write touching an ambiguous entity is deferred
|
|
252
|
-
|
|
282
|
+
produced one fact, and a write touching an ambiguous entity is deferred rather than
|
|
283
|
+
stored. The deferral is still the cost; what has changed is that the call now says so
|
|
284
|
+
instead of returning as though it had succeeded.
|
|
253
285
|
|
|
254
286
|
**Any MCP client.** A coding assistant, a chatbot, an ops agent, or something built in
|
|
255
287
|
house. Coding agents are where this is proven, not what it is limited to.
|
|
256
288
|
|
|
257
289
|
## Numbers, and how they were taken
|
|
258
290
|
|
|
259
|
-
Every figure comes from this repository or a live store,
|
|
260
|
-
|
|
261
|
-
difference nobody sized is not a result.
|
|
291
|
+
Every figure comes from this repository or a live store, with the command that reproduces
|
|
292
|
+
it on yours and the size of the store it was taken against. The corpus is small and the
|
|
293
|
+
noise floor is stated, because a difference nobody sized is not a result.
|
|
294
|
+
|
|
295
|
+
Two of these describe the store rather than the product. `eval --context` and
|
|
296
|
+
`eval --ablate` build their queries from the facts they are scoring, so the labels are
|
|
297
|
+
free and the absolute values belong to this store alone; they are honest about a
|
|
298
|
+
difference between configurations and say nothing about how echo-mem would rank on
|
|
299
|
+
somebody else's data. The two external rows are the ones to compare against anything.
|
|
262
300
|
|
|
263
301
|
| Measure | Value | Reproduce |
|
|
264
302
|
|---|---|---|
|
|
265
|
-
| Context per recall vs injecting everything | **96.7% less
|
|
303
|
+
| Context per recall vs injecting everything | **96.7% less** on a 325 fact store, hit@10 0.872 over 1,190 queries derived from their own answers, so read it as a token ratio with a floor attached rather than as accuracy | `echo-memory eval --context` |
|
|
266
304
|
| The same saving across 8x of corpus growth | 75.5% at 32 facts rising to **96.4% at 261**, hit@10 0.900 to 0.946 | `echo-memory eval --context --sweep` |
|
|
267
305
|
| LoCoMo retrieval, 1,982 questions, 5,882 turns | recall@10 **0.601**, hit@10 0.658, MRR 0.460, session@10 0.850 | `echo-memory eval-external locomo` |
|
|
268
306
|
| LongMemEval retrieval, 90 questions, 15 per type | session@10 **0.937**, recall@10 0.727, MRR 0.428 | `echo-memory eval-external longmemeval --per-type 15` |
|
|
269
307
|
| Lexical BM25 against `ts_rank` | **+0.0271** MRR on entity_pair [+0.0083, +0.0481] and on multihop [+0.0166, +0.0381], the other two shapes inside noise, none worse | `echo-memory eval --ablate`, the `without BM25` row with its sign reversed |
|
|
270
308
|
| Server side model calls per write | **0** | `echo-memory benchmark` |
|
|
271
|
-
| Write, query, digest latency (median) |
|
|
309
|
+
| Write, query, digest latency (median) | 24ms, 17ms, 4ms, against a 250 fact scope | `echo-memory benchmark` |
|
|
272
310
|
| Entity resolution AUC | 0.666, 95% CI [0.421, 0.881] | `echo-memory calibrate` |
|
|
273
311
|
|
|
274
312
|
That last row is the one that went the wrong way, and it is here on purpose. The interval
|
|
@@ -401,18 +439,23 @@ the target this architecture is built toward.
|
|
|
401
439
|
|
|
402
440
|
## Hosted
|
|
403
441
|
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
442
|
+
[app.echo-mem.com](https://app.echo-mem.com) runs the database for you: **$149 a month**
|
|
443
|
+
for 1,500,000 units, where a unit is one fact written or one fact returned. It is paid
|
|
444
|
+
from the first key, because hosting is the thing it charges for, and it runs the same
|
|
445
|
+
published package you would install yourself.
|
|
446
|
+
|
|
447
|
+
Running it yourself is free for development, testing and evaluation at any size, and free
|
|
448
|
+
in production for organisations under 50 people and under $5M revenue, with no account and
|
|
449
|
+
no feature held back. Above either threshold, production use needs an agreement:
|
|
450
|
+
[talk to us](mailto:hello@echo-mem.com).
|
|
409
451
|
|
|
410
452
|
<details>
|
|
411
453
|
<summary>Contributing</summary>
|
|
412
454
|
|
|
413
455
|
See [`CONTRIBUTING.md`](CONTRIBUTING.md). Issues and pull requests welcome; please read the
|
|
414
|
-
design docs first so proposals fit the staged build plan.
|
|
415
|
-
|
|
456
|
+
design docs first so proposals fit the staged build plan. Commits need a sign-off line,
|
|
457
|
+
`git commit -s`, which is the [Developer Certificate of Origin](DCO.md). There is no
|
|
458
|
+
contributor agreement to read.
|
|
416
459
|
|
|
417
460
|
The most useful contribution is a measurement that disagrees with one of the numbers
|
|
418
461
|
above. Run `echo-memory eval`, `calibrate` or `benchmark` on your own store and open an
|
|
@@ -422,27 +465,32 @@ issue with the output.
|
|
|
422
465
|
|
|
423
466
|
## License
|
|
424
467
|
|
|
425
|
-
|
|
468
|
+
**Apache 2.0.** See [`LICENSE`](LICENSE). Run it, fork it, build on it, ship it in your
|
|
469
|
+
product, at any size, with no agreement and nobody to ask.
|
|
426
470
|
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
| Development, testing, evaluation, research, teaching | free, any size |
|
|
433
|
-
| Production, under 50 employees and under $5M revenue | free |
|
|
434
|
-
| Production, above that | [talk to us](mailto:hello@echo-mem.com) |
|
|
435
|
-
| Offering it to third parties as a hosted service | [talk to us](mailto:hello@echo-mem.com) |
|
|
471
|
+
For about a month this was not true. Versions 0.5.0 to 0.5.5 shipped under the Business
|
|
472
|
+
Source License, which made production use free only below fifty people and $5M of revenue.
|
|
473
|
+
That is withdrawn. Ateleir Tech holds the copyright in the whole work and relicenses all of
|
|
474
|
+
it, those versions included, so the grant only ever got wider and nobody lost a right they
|
|
475
|
+
already had.
|
|
436
476
|
|
|
437
|
-
|
|
438
|
-
|
|
477
|
+
The reasoning, since a project that changes its licence twice owes you one: the restriction
|
|
478
|
+
was protecting the wrong thing. What makes this hard to run is not the source, it is a
|
|
479
|
+
Postgres with Apache AGE and pgvector that somebody has to operate, back up and upgrade.
|
|
480
|
+
[The hosted plan](https://echo-mem.com) sells exactly that and is unaffected by the
|
|
481
|
+
licence. Meanwhile the restriction was costing the thing the project most needs, which is
|
|
482
|
+
for people to be able to use it without reading a grant first.
|
|
439
483
|
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
exists so nobody has to work that out from a git history. The Apache text those versions
|
|
443
|
-
were released under is kept at [`LICENSE-APACHE-2.0`](LICENSE-APACHE-2.0).
|
|
484
|
+
What is not Apache 2.0 is the hosted service itself: the metering, billing and tenancy that
|
|
485
|
+
only exist because somebody is being invoiced. None of it sits in the read or write path.
|
|
444
486
|
|
|
445
487
|
<!-- The MCP registry proves you own a PyPI package by finding this line in the
|
|
446
488
|
package's own description. It has to survive into the built distribution,
|
|
447
|
-
which is why it lives in the README rather than in a workflow.
|
|
448
|
-
|
|
489
|
+
which is why it lives in the README rather than in a workflow.
|
|
490
|
+
|
|
491
|
+
It is checked against the README of the version ALREADY ON PyPI, which
|
|
492
|
+
makes the ordering strict: this name cannot be published to the registry
|
|
493
|
+
until a release carrying this line has reached PyPI first. The release
|
|
494
|
+
workflow does PyPI before the registry for exactly that reason, so the
|
|
495
|
+
first automated publish is the first release after this change. -->
|
|
496
|
+
mcp-name: com.echo-mem/echo-mem
|
|
@@ -1,42 +1,26 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: echo-mem
|
|
3
|
-
Version: 0.5.4
|
|
4
|
-
Summary: A long-horizon memory architecture for AI agents
|
|
5
|
-
License-Expression: BUSL-1.1
|
|
6
|
-
Requires-Python: >=3.11
|
|
7
|
-
Description-Content-Type: text/markdown
|
|
8
|
-
License-File: LICENSE
|
|
9
|
-
License-File: LICENSE-APACHE-2.0
|
|
10
|
-
Requires-Dist: psycopg[binary]<4,>=3.2
|
|
11
|
-
Requires-Dist: psycopg-pool<4,>=3.2
|
|
12
|
-
Requires-Dist: pgvector<1,>=0.3
|
|
13
|
-
Requires-Dist: alembic<2,>=1.13
|
|
14
|
-
Requires-Dist: sqlalchemy<3,>=2
|
|
15
|
-
Requires-Dist: mcp<3,>=2.0
|
|
16
|
-
Requires-Dist: sentence-transformers<4,>=3
|
|
17
|
-
Provides-Extra: dev
|
|
18
|
-
Requires-Dist: pytest<9,>=8; extra == "dev"
|
|
19
|
-
Requires-Dist: ruff<1,>=0.6; extra == "dev"
|
|
20
|
-
Requires-Dist: build<2,>=1; extra == "dev"
|
|
21
|
-
Requires-Dist: twine<7,>=5; extra == "dev"
|
|
22
|
-
Dynamic: license-file
|
|
23
|
-
|
|
24
1
|
# Echo Memory
|
|
25
2
|
|
|
26
3
|
[](https://github.com/echo-mem/echo-mem/actions/workflows/ci.yml)
|
|
27
4
|
[](https://pypi.org/project/echo-mem/)
|
|
28
5
|
[](https://pypi.org/project/echo-mem/)
|
|
29
|
-
[](LICENSE)
|
|
30
7
|
|
|
31
8
|
**Shared memory for AI agents, as a graph in your own database.** What Claude Code learns,
|
|
32
9
|
Cursor and Codex can recall. Every fact records who wrote it and when, and the server
|
|
33
10
|
never calls a model to store one.
|
|
34
11
|
|
|
12
|
+

|
|
13
|
+
|
|
14
|
+
<sub>Every line above is real output, captured from these commands against a throwaway
|
|
15
|
+
database. The transcript is at
|
|
16
|
+
[`.github/branding/demo-transcript.txt`](.github/branding/demo-transcript.txt).</sub>
|
|
17
|
+
|
|
35
18
|
> Your agents start every session from zero. The usual fix is a notes file you paste into
|
|
36
19
|
> context, which grows until it is mostly irrelevant to whatever you are asking. Echo
|
|
37
20
|
> Memory is the other shape: facts connected to each other, and a query that returns the
|
|
38
|
-
> few that matter. On the author's own store that is **96.7% less context** for
|
|
39
|
-
> answer, with the answer still present 87.2% of the time across 1,190
|
|
21
|
+
> few that matter. On the author's own 325 fact store that is **96.7% less context** for
|
|
22
|
+
> the same answer, with the answer still present 87.2% of the time across 1,190 queries
|
|
23
|
+
> the harness derived from their own answers.
|
|
40
24
|
|
|
41
25
|
```
|
|
42
26
|
write_episode query_memory
|
|
@@ -199,10 +183,34 @@ could not answer the first question a post mortem asks. `query_memory` takes `as
|
|
|
199
183
|
unix seconds and every channel honours it: vector, full text, the graph hop, the digest.
|
|
200
184
|
|
|
201
185
|
Supersession is what makes that more than a curiosity. Writing the same source, target and
|
|
202
|
-
relation again does not edit the old fact, it ends it: the old
|
|
203
|
-
stays queryable. Nothing is ever rewritten, so the history is
|
|
204
|
-
reconstructed, which is the property the memory reconsolidation
|
|
205
|
-
the reason this project refuses that idea.
|
|
186
|
+
relation again with a **changed** claim does not edit the old fact, it ends it: the old
|
|
187
|
+
edge takes a `t_invalid` and stays queryable. Nothing is ever rewritten, so the history is
|
|
188
|
+
real rather than reconstructed, which is the property the memory reconsolidation
|
|
189
|
+
literature gives up and the reason this project refuses that idea.
|
|
190
|
+
|
|
191
|
+
Restating an **unchanged** claim is not a change and no longer counts as one. If the fact
|
|
192
|
+
text, the confidence and the causal hint all match the edge already there, the write is
|
|
193
|
+
skipped and reported under `restated`. It used to create a second edge, end the first, and
|
|
194
|
+
emit a supersession whose `before_fact` equalled its `after_fact`. That is the mechanism
|
|
195
|
+
behind one customer edge carrying 47 versions of a single sentence, and behind 543 writes
|
|
196
|
+
producing 112 facts while every one of them was billed. It also makes a retry safe: with
|
|
197
|
+
no idempotency key, a caller retrying a write that had actually landed used to burn a
|
|
198
|
+
version on it.
|
|
199
|
+
|
|
200
|
+
**Every write answers whether it stored anything.** `write_episode` can end with an empty
|
|
201
|
+
`edges_created` four different ways, and from the caller's side they used to be
|
|
202
|
+
indistinguishable without knowing which other key to inspect. Each one now reports
|
|
203
|
+
`stored: false` and names itself in `not_stored`: `refused` (validation rejected it),
|
|
204
|
+
`deferred` (an entity mention was close enough to an existing node to be worth asking
|
|
205
|
+
about and not close enough to merge), `unchanged` (every fact already existed word for
|
|
206
|
+
word) and `no_facts` (the episode asserted none). A refusal carries the same keys as a
|
|
207
|
+
success, so one check works on every path, and `retryable` separates a database blip worth
|
|
208
|
+
retrying from a validation error that will fail forever. A write that stored some of its
|
|
209
|
+
facts and held the rest says `partial`.
|
|
210
|
+
|
|
211
|
+
The deferral is the one that cost real data, because it looks most like success: a well
|
|
212
|
+
formed response, no error, `isError` false, and nothing written. A customer loading 26,633
|
|
213
|
+
facts read that as 26,633 successes and stored 1,650.
|
|
206
214
|
|
|
207
215
|
**Provenance on every fact.** Who wrote it, which tool, which project, when, and which
|
|
208
216
|
reads returned it. A superseded fact is never deleted. It stops being drawn and stays
|
|
@@ -248,27 +256,34 @@ Zep/Graphiti, the closest architectural match, whose own description of ingestio
|
|
|
248
256
|
The obvious reply is that cheap writes are cheap because they do less, and that reply is
|
|
249
257
|
correct on the mechanism. [`docs/WRITE-COST.md`](docs/WRITE-COST.md) answers it properly,
|
|
250
258
|
including the two measured costs of the choice: the Stop gate fired seven times and
|
|
251
|
-
produced one fact, and a write touching an ambiguous entity is deferred
|
|
252
|
-
|
|
259
|
+
produced one fact, and a write touching an ambiguous entity is deferred rather than
|
|
260
|
+
stored. The deferral is still the cost; what has changed is that the call now says so
|
|
261
|
+
instead of returning as though it had succeeded.
|
|
253
262
|
|
|
254
263
|
**Any MCP client.** A coding assistant, a chatbot, an ops agent, or something built in
|
|
255
264
|
house. Coding agents are where this is proven, not what it is limited to.
|
|
256
265
|
|
|
257
266
|
## Numbers, and how they were taken
|
|
258
267
|
|
|
259
|
-
Every figure comes from this repository or a live store,
|
|
260
|
-
|
|
261
|
-
difference nobody sized is not a result.
|
|
268
|
+
Every figure comes from this repository or a live store, with the command that reproduces
|
|
269
|
+
it on yours and the size of the store it was taken against. The corpus is small and the
|
|
270
|
+
noise floor is stated, because a difference nobody sized is not a result.
|
|
271
|
+
|
|
272
|
+
Two of these describe the store rather than the product. `eval --context` and
|
|
273
|
+
`eval --ablate` build their queries from the facts they are scoring, so the labels are
|
|
274
|
+
free and the absolute values belong to this store alone; they are honest about a
|
|
275
|
+
difference between configurations and say nothing about how echo-mem would rank on
|
|
276
|
+
somebody else's data. The two external rows are the ones to compare against anything.
|
|
262
277
|
|
|
263
278
|
| Measure | Value | Reproduce |
|
|
264
279
|
|---|---|---|
|
|
265
|
-
| Context per recall vs injecting everything | **96.7% less
|
|
280
|
+
| Context per recall vs injecting everything | **96.7% less** on a 325 fact store, hit@10 0.872 over 1,190 queries derived from their own answers, so read it as a token ratio with a floor attached rather than as accuracy | `echo-memory eval --context` |
|
|
266
281
|
| The same saving across 8x of corpus growth | 75.5% at 32 facts rising to **96.4% at 261**, hit@10 0.900 to 0.946 | `echo-memory eval --context --sweep` |
|
|
267
282
|
| LoCoMo retrieval, 1,982 questions, 5,882 turns | recall@10 **0.601**, hit@10 0.658, MRR 0.460, session@10 0.850 | `echo-memory eval-external locomo` |
|
|
268
283
|
| LongMemEval retrieval, 90 questions, 15 per type | session@10 **0.937**, recall@10 0.727, MRR 0.428 | `echo-memory eval-external longmemeval --per-type 15` |
|
|
269
284
|
| Lexical BM25 against `ts_rank` | **+0.0271** MRR on entity_pair [+0.0083, +0.0481] and on multihop [+0.0166, +0.0381], the other two shapes inside noise, none worse | `echo-memory eval --ablate`, the `without BM25` row with its sign reversed |
|
|
270
285
|
| Server side model calls per write | **0** | `echo-memory benchmark` |
|
|
271
|
-
| Write, query, digest latency (median) |
|
|
286
|
+
| Write, query, digest latency (median) | 24ms, 17ms, 4ms, against a 250 fact scope | `echo-memory benchmark` |
|
|
272
287
|
| Entity resolution AUC | 0.666, 95% CI [0.421, 0.881] | `echo-memory calibrate` |
|
|
273
288
|
|
|
274
289
|
That last row is the one that went the wrong way, and it is here on purpose. The interval
|
|
@@ -401,18 +416,23 @@ the target this architecture is built toward.
|
|
|
401
416
|
|
|
402
417
|
## Hosted
|
|
403
418
|
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
419
|
+
[app.echo-mem.com](https://app.echo-mem.com) runs the database for you: **$149 a month**
|
|
420
|
+
for 1,500,000 units, where a unit is one fact written or one fact returned. It is paid
|
|
421
|
+
from the first key, because hosting is the thing it charges for, and it runs the same
|
|
422
|
+
published package you would install yourself.
|
|
423
|
+
|
|
424
|
+
Running it yourself is free for development, testing and evaluation at any size, and free
|
|
425
|
+
in production for organisations under 50 people and under $5M revenue, with no account and
|
|
426
|
+
no feature held back. Above either threshold, production use needs an agreement:
|
|
427
|
+
[talk to us](mailto:hello@echo-mem.com).
|
|
409
428
|
|
|
410
429
|
<details>
|
|
411
430
|
<summary>Contributing</summary>
|
|
412
431
|
|
|
413
432
|
See [`CONTRIBUTING.md`](CONTRIBUTING.md). Issues and pull requests welcome; please read the
|
|
414
|
-
design docs first so proposals fit the staged build plan.
|
|
415
|
-
|
|
433
|
+
design docs first so proposals fit the staged build plan. Commits need a sign-off line,
|
|
434
|
+
`git commit -s`, which is the [Developer Certificate of Origin](DCO.md). There is no
|
|
435
|
+
contributor agreement to read.
|
|
416
436
|
|
|
417
437
|
The most useful contribution is a measurement that disagrees with one of the numbers
|
|
418
438
|
above. Run `echo-memory eval`, `calibrate` or `benchmark` on your own store and open an
|
|
@@ -422,27 +442,32 @@ issue with the output.
|
|
|
422
442
|
|
|
423
443
|
## License
|
|
424
444
|
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
The source is public and stays public. What changed on 25 September 2026 is who may run it
|
|
428
|
-
in production without an agreement:
|
|
445
|
+
**Apache 2.0.** See [`LICENSE`](LICENSE). Run it, fork it, build on it, ship it in your
|
|
446
|
+
product, at any size, with no agreement and nobody to ask.
|
|
429
447
|
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
| Offering it to third parties as a hosted service | [talk to us](mailto:hello@echo-mem.com) |
|
|
448
|
+
For about a month this was not true. Versions 0.5.0 to 0.5.5 shipped under the Business
|
|
449
|
+
Source License, which made production use free only below fifty people and $5M of revenue.
|
|
450
|
+
That is withdrawn. Ateleir Tech holds the copyright in the whole work and relicenses all of
|
|
451
|
+
it, those versions included, so the grant only ever got wider and nobody lost a right they
|
|
452
|
+
already had.
|
|
436
453
|
|
|
437
|
-
|
|
438
|
-
|
|
454
|
+
The reasoning, since a project that changes its licence twice owes you one: the restriction
|
|
455
|
+
was protecting the wrong thing. What makes this hard to run is not the source, it is a
|
|
456
|
+
Postgres with Apache AGE and pgvector that somebody has to operate, back up and upgrade.
|
|
457
|
+
[The hosted plan](https://echo-mem.com) sells exactly that and is unaffected by the
|
|
458
|
+
licence. Meanwhile the restriction was costing the thing the project most needs, which is
|
|
459
|
+
for people to be able to use it without reading a grant first.
|
|
439
460
|
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
exists so nobody has to work that out from a git history. The Apache text those versions
|
|
443
|
-
were released under is kept at [`LICENSE-APACHE-2.0`](LICENSE-APACHE-2.0).
|
|
461
|
+
What is not Apache 2.0 is the hosted service itself: the metering, billing and tenancy that
|
|
462
|
+
only exist because somebody is being invoiced. None of it sits in the read or write path.
|
|
444
463
|
|
|
445
464
|
<!-- The MCP registry proves you own a PyPI package by finding this line in the
|
|
446
465
|
package's own description. It has to survive into the built distribution,
|
|
447
|
-
which is why it lives in the README rather than in a workflow.
|
|
448
|
-
|
|
466
|
+
which is why it lives in the README rather than in a workflow.
|
|
467
|
+
|
|
468
|
+
It is checked against the README of the version ALREADY ON PyPI, which
|
|
469
|
+
makes the ordering strict: this name cannot be published to the registry
|
|
470
|
+
until a release carrying this line has reached PyPI first. The release
|
|
471
|
+
workflow does PyPI before the registry for exactly that reason, so the
|
|
472
|
+
first automated publish is the first release after this change. -->
|
|
473
|
+
mcp-name: com.echo-mem/echo-mem
|
|
@@ -6,17 +6,16 @@
|
|
|
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.5.
|
|
9
|
+
version = "0.5.6"
|
|
10
10
|
description = "A long-horizon memory architecture for AI agents"
|
|
11
11
|
readme = "README.md"
|
|
12
|
-
#
|
|
13
|
-
#
|
|
14
|
-
#
|
|
15
|
-
#
|
|
16
|
-
#
|
|
17
|
-
|
|
18
|
-
license = "
|
|
19
|
-
license-files = ["LICENSE", "LICENSE-APACHE-2.0"]
|
|
12
|
+
# An SPDX expression, not an inlined licence text: pip, PyPI and every
|
|
13
|
+
# scanner read this field as the fact of the matter, so it has to agree with
|
|
14
|
+
# LICENSE. It said Apache-2.0 for a while after the project moved to BSL,
|
|
15
|
+
# which was a false statement to exactly the people who check metadata
|
|
16
|
+
# instead of reading a file. tests/unit/test_licence_claims.py pins it.
|
|
17
|
+
license = "Apache-2.0"
|
|
18
|
+
license-files = ["LICENSE", "NOTICE"]
|
|
20
19
|
requires-python = ">=3.11"
|
|
21
20
|
dependencies = [
|
|
22
21
|
"psycopg[binary]>=3.2,<4",
|
|
@@ -25,7 +24,7 @@ dependencies = [
|
|
|
25
24
|
"alembic>=1.13,<2",
|
|
26
25
|
"sqlalchemy>=2,<3",
|
|
27
26
|
"mcp>=2.0,<3",
|
|
28
|
-
"sentence-transformers>=3,<
|
|
27
|
+
"sentence-transformers>=3,<7",
|
|
29
28
|
]
|
|
30
29
|
|
|
31
30
|
[project.scripts]
|
|
@@ -33,10 +32,10 @@ echo-memory = "echo_memory.cli.main:main"
|
|
|
33
32
|
|
|
34
33
|
[project.optional-dependencies]
|
|
35
34
|
dev = [
|
|
36
|
-
"pytest>=8,<
|
|
35
|
+
"pytest>=8,<10",
|
|
37
36
|
"ruff>=0.6,<1",
|
|
38
37
|
"build>=1,<2",
|
|
39
|
-
"twine>=5,<
|
|
38
|
+
"twine>=5,<8",
|
|
40
39
|
]
|
|
41
40
|
|
|
42
41
|
[build-system]
|