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.
Files changed (118) hide show
  1. echo_mem-0.5.6/NOTICE +10 -0
  2. {echo_mem-0.5.4 → echo_mem-0.5.6}/PKG-INFO +93 -45
  3. echo_mem-0.5.4/src/echo_mem.egg-info/PKG-INFO → echo_mem-0.5.6/README.md +87 -62
  4. {echo_mem-0.5.4 → echo_mem-0.5.6}/pyproject.toml +11 -12
  5. echo_mem-0.5.4/README.md → echo_mem-0.5.6/src/echo_mem.egg-info/PKG-INFO +110 -39
  6. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_mem.egg-info/SOURCES.txt +8 -1
  7. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_mem.egg-info/requires.txt +3 -3
  8. echo_mem-0.5.6/src/echo_memory/cli/distil.py +128 -0
  9. echo_mem-0.5.6/src/echo_memory/cli/forget.py +148 -0
  10. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/main.py +71 -0
  11. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/recall.py +20 -2
  12. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/client.py +4 -1
  13. echo_mem-0.5.6/src/echo_memory/distil/__init__.py +15 -0
  14. echo_mem-0.5.6/src/echo_memory/distil/candidates.py +195 -0
  15. echo_mem-0.5.6/src/echo_memory/distil/transcripts.py +183 -0
  16. echo_mem-0.5.6/src/echo_memory/erasure.py +531 -0
  17. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/eval/independent.py +2 -2
  18. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/infra/logging.py +13 -1
  19. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/ingestion/write_episode.py +117 -15
  20. echo_mem-0.5.6/src/echo_memory/migrations/versions/0028_erasure_events.py +92 -0
  21. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/retrieval/query_memory.py +13 -1
  22. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/server.py +18 -10
  23. echo_mem-0.5.4/LICENSE +0 -96
  24. /echo_mem-0.5.4/LICENSE-APACHE-2.0 → /echo_mem-0.5.6/LICENSE +0 -0
  25. {echo_mem-0.5.4 → echo_mem-0.5.6}/setup.cfg +0 -0
  26. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_mem.egg-info/dependency_links.txt +0 -0
  27. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_mem.egg-info/entry_points.txt +0 -0
  28. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_mem.egg-info/top_level.txt +0 -0
  29. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/__init__.py +0 -0
  30. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/audit/__init__.py +0 -0
  31. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/audit/get_audit_log.py +0 -0
  32. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/__init__.py +0 -0
  33. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/adopt.py +0 -0
  34. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/analyse.py +0 -0
  35. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/benchmark.py +0 -0
  36. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/calibrate.py +0 -0
  37. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/connect.py +0 -0
  38. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/dashboard.py +0 -0
  39. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/dashboard_html.py +0 -0
  40. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/export.py +0 -0
  41. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/graph.py +0 -0
  42. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/health.py +0 -0
  43. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/hooks.py +0 -0
  44. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/infer_causal.py +0 -0
  45. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/initdb.py +0 -0
  46. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/install.py +0 -0
  47. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/judge.py +0 -0
  48. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/llm.py +0 -0
  49. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/merge.py +0 -0
  50. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/queue.py +0 -0
  51. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/quickstart.py +0 -0
  52. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/reattribute.py +0 -0
  53. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/reattribute_cmd.py +0 -0
  54. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/reconcile.py +0 -0
  55. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/reindex.py +0 -0
  56. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/session_start.py +0 -0
  57. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/skill.py +0 -0
  58. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/status.py +0 -0
  59. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/stop_gate.py +0 -0
  60. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/trial.py +0 -0
  61. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/unmerge.py +0 -0
  62. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/cli/why.py +0 -0
  63. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/eval/__init__.py +0 -0
  64. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/eval/external.py +0 -0
  65. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/eval/retrieval.py +0 -0
  66. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/eval/sweep.py +0 -0
  67. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/graph/__init__.py +0 -0
  68. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/graph/communities.py +0 -0
  69. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/infra/__init__.py +0 -0
  70. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/infra/config.py +0 -0
  71. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/infra/db.py +0 -0
  72. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/infra/pool.py +0 -0
  73. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/infra/project.py +0 -0
  74. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/ingestion/__init__.py +0 -0
  75. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/ingestion/activity.py +0 -0
  76. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/ingestion/bootstrap.py +0 -0
  77. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/ingestion/capture.py +0 -0
  78. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/ingestion/embeddings.py +0 -0
  79. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/ingestion/neighbourhood.py +0 -0
  80. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/ingestion/resolution.py +0 -0
  81. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/env.py +0 -0
  82. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0001_initial_schema.py +0 -0
  83. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0002_trial_observations.py +0 -0
  84. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0003_project_and_agent_provenance.py +0 -0
  85. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0004_bootstrap_state.py +0 -0
  86. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0005_recall_save_guards.py +0 -0
  87. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0006_project_analysis.py +0 -0
  88. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0007_backfill_unknown_agent.py +0 -0
  89. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0008_read_events.py +0 -0
  90. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0009_read_event_attribution.py +0 -0
  91. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0010_stop_gate_fired.py +0 -0
  92. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0011_backfill_absent_agent.py +0 -0
  93. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0012_read_event_agent.py +0 -0
  94. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0013_active_fact_indexes.py +0 -0
  95. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0014_session_activity.py +0 -0
  96. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0015_retracted_observations.py +0 -0
  97. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0016_one_node_per_name.py +0 -0
  98. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0017_writer_version.py +0 -0
  99. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0018_trial_runs_are_history.py +0 -0
  100. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0019_versions_expected_since.py +0 -0
  101. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0020_who_closed_a_queued_document.py +0 -0
  102. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0021_delivery_evidence.py +0 -0
  103. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0022_independent_evaluation.py +0 -0
  104. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0023_second_judge.py +0 -0
  105. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0024_node_by_id.py +0 -0
  106. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0025_lexical_statistics.py +0 -0
  107. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0026_late_causal_extraction.py +0 -0
  108. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/migrations/versions/0027_lexical_staleness_without_a_scan.py +0 -0
  109. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/retrieval/__init__.py +0 -0
  110. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/retrieval/bm25.py +0 -0
  111. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/retrieval/causality.py +0 -0
  112. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/retrieval/fusion.py +0 -0
  113. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/retrieval/salience.py +0 -0
  114. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/skill/SKILL.md +0 -0
  115. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/trial/__init__.py +0 -0
  116. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/trial/check.py +0 -0
  117. {echo_mem-0.5.4 → echo_mem-0.5.6}/src/echo_memory/trial/observations.py +0 -0
  118. {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.4
3
+ Version: 0.5.6
4
4
  Summary: A long-horizon memory architecture for AI agents
5
- License-Expression: BUSL-1.1
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: LICENSE-APACHE-2.0
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<4,>=3
16
+ Requires-Dist: sentence-transformers<7,>=3
17
17
  Provides-Extra: dev
18
- Requires-Dist: pytest<9,>=8; extra == "dev"
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<7,>=5; extra == "dev"
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
  [![CI](https://github.com/echo-mem/echo-mem/actions/workflows/ci.yml/badge.svg)](https://github.com/echo-mem/echo-mem/actions/workflows/ci.yml)
27
27
  [![PyPI](https://img.shields.io/pypi/v/echo-mem)](https://pypi.org/project/echo-mem/)
28
28
  [![Python](https://img.shields.io/pypi/pyversions/echo-mem)](https://pypi.org/project/echo-mem/)
29
- [![License](https://img.shields.io/badge/license-BSL%201.1-blue)](LICENSE)
29
+ [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](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
+ ![Claude Code writes a decision with no model call; Cursor recalls it three days later and the fact still names who wrote it](.github/branding/demo.gif)
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 the same
39
- > answer, with the answer still present 87.2% of the time across 1,190 questions.
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 edge takes a `t_invalid` and
203
- stays queryable. Nothing is ever rewritten, so the history is real rather than
204
- reconstructed, which is the property the memory reconsolidation literature gives up and
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 while the call
252
- returns as though it succeeded.
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, on a date, with the command that
260
- reproduces it on yours. The corpus is small and the noise floor is stated, because a
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**, hit@10 0.872 over 1,190 questions | `echo-memory eval --context` |
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) | 15ms, 8ms, 1ms | `echo-memory benchmark` |
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
- Running it yourself is free under the Business Source License for any non production use,
405
- and free in production for organisations under 50 people and under $5M revenue, with no
406
- account and no feature held
407
- back. [app.echo-mem.com](https://app.echo-mem.com) runs the database for you at $99 a
408
- month if you would rather not.
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. A first pull request is asked to
415
- sign the [Contributor License Agreement](CLA.md), once, in the PR thread.
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
- Business Source License 1.1. See [`LICENSE`](LICENSE).
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
- The source is public and stays public. What changed on 25 September 2026 is who may run it
428
- in production without an agreement:
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
- Each released version converts to **Apache 2.0 four years after it is published**, and that
438
- conversion is automatic and irrevocable.
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
- Versions published before this change remain under Apache 2.0 permanently. That includes
441
- everything up to and including 0.4.1 on PyPI. Relicensing cannot reach back, and this note
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
- mcp-name: io.github.ayushcodes10/echo-mem
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
  [![CI](https://github.com/echo-mem/echo-mem/actions/workflows/ci.yml/badge.svg)](https://github.com/echo-mem/echo-mem/actions/workflows/ci.yml)
27
4
  [![PyPI](https://img.shields.io/pypi/v/echo-mem)](https://pypi.org/project/echo-mem/)
28
5
  [![Python](https://img.shields.io/pypi/pyversions/echo-mem)](https://pypi.org/project/echo-mem/)
29
- [![License](https://img.shields.io/badge/license-BSL%201.1-blue)](LICENSE)
6
+ [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](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
+ ![Claude Code writes a decision with no model call; Cursor recalls it three days later and the fact still names who wrote it](.github/branding/demo.gif)
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 the same
39
- > answer, with the answer still present 87.2% of the time across 1,190 questions.
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 edge takes a `t_invalid` and
203
- stays queryable. Nothing is ever rewritten, so the history is real rather than
204
- reconstructed, which is the property the memory reconsolidation literature gives up and
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 while the call
252
- returns as though it succeeded.
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, on a date, with the command that
260
- reproduces it on yours. The corpus is small and the noise floor is stated, because a
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**, hit@10 0.872 over 1,190 questions | `echo-memory eval --context` |
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) | 15ms, 8ms, 1ms | `echo-memory benchmark` |
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
- Running it yourself is free under the Business Source License for any non production use,
405
- and free in production for organisations under 50 people and under $5M revenue, with no
406
- account and no feature held
407
- back. [app.echo-mem.com](https://app.echo-mem.com) runs the database for you at $99 a
408
- month if you would rather not.
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. A first pull request is asked to
415
- sign the [Contributor License Agreement](CLA.md), once, in the PR thread.
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
- Business Source License 1.1. See [`LICENSE`](LICENSE).
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
- | 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) |
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
- Each released version converts to **Apache 2.0 four years after it is published**, and that
438
- conversion is automatic and irrevocable.
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
- Versions published before this change remain under Apache 2.0 permanently. That includes
441
- everything up to and including 0.4.1 on PyPI. Relicensing cannot reach back, and this note
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
- mcp-name: io.github.ayushcodes10/echo-mem
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.4"
9
+ version = "0.5.6"
10
10
  description = "A long-horizon memory architecture for AI agents"
11
11
  readme = "README.md"
12
- # BUSL-1.1 is the SPDX identifier for the Business Source License 1.1, so
13
- # the metadata can state it rather than inline the whole licence text.
14
- # license-files ships both: LICENSE is what this version is under, and
15
- # LICENSE-APACHE-2.0 is what everything up to 0.4.1 went out under and stays
16
- # under. Saying "Apache-2.0" here would be a false statement in package
17
- # metadata that pip, PyPI and every licence scanner would read as fact.
18
- license = "BUSL-1.1"
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,<4",
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,<9",
35
+ "pytest>=8,<10",
37
36
  "ruff>=0.6,<1",
38
37
  "build>=1,<2",
39
- "twine>=5,<7",
38
+ "twine>=5,<8",
40
39
  ]
41
40
 
42
41
  [build-system]