echo-mem 0.3.0__tar.gz → 0.4.1__tar.gz

echo_mem-0.4.1/PKG-INFO

@@ -0,0 +1,315 @@
+Metadata-Version: 2.4
+Name: echo-mem
+Version: 0.4.1
+Summary: A long-horizon memory architecture for AI agents
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psycopg[binary]<4,>=3.2
+Requires-Dist: psycopg-pool<4,>=3.2
+Requires-Dist: pgvector<1,>=0.3
+Requires-Dist: alembic<2,>=1.13
+Requires-Dist: sqlalchemy<3,>=2
+Requires-Dist: mcp<3,>=2.0
+Requires-Dist: sentence-transformers<4,>=3
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Requires-Dist: ruff<1,>=0.6; extra == "dev"
+Requires-Dist: build<2,>=1; extra == "dev"
+Requires-Dist: twine<7,>=5; extra == "dev"
+Dynamic: license-file
+
+# Echo Memory
+
+[![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)
+[![PyPI](https://img.shields.io/pypi/v/echo-mem)](https://pypi.org/project/echo-mem/)
+[![Python](https://img.shields.io/pypi/pyversions/echo-mem)](https://pypi.org/project/echo-mem/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+
+**Shared memory for AI agents, as a graph in your own database.** What Claude Code learns,
+Cursor and Codex can recall. Every fact records who wrote it and when, and the server
+never calls a model to store one.
+
+> Your agents start every session from zero. The usual fix is a notes file you paste into
+> context, which grows until it is mostly irrelevant to whatever you are asking. Echo
+> Memory is the other shape: facts connected to each other, and a query that returns the
+> few that matter. On the author's own store that is **96.7% less context** for the same
+> answer, with the answer still present 87.2% of the time across 1,190 questions.
+
+```
+write_episode                          query_memory
+  billing ──uses──▸ Razorpay             "how do we take payments"
+    │ written by claude-code               ▸ billing uses Razorpay, not Stripe
+    │ supersedes ──▸ Stripe                  written by claude-code, 3 days ago
+    └ no model invoked                     ▸ 1,372 tokens, not 41,838
+```
+
+## Install
+
+**Requires:** Python 3.11+ and Docker (for the database).
+
+```bash
+pipx install echo-mem
+echo-memory quickstart
+```
+
+`quickstart` starts the database, applies the schema, and prints the `claude mcp add`
+line that registers it, filled in with the port it actually used. The Postgres image is
+published, so nothing compiles.
+
+Or use the hosted service and run no database at all:
+
+```bash
+pipx install echo-mem
+echo-memory connect <key>          # a key from https://app.echo-mem.com
+```
+
+Then once per machine, so an agent knows *when* to record and recall rather than only
+that the tools exist:
+
+```bash
+echo-memory install --global
+```
+
+> **Restart your client afterwards.** An MCP server is a long lived process that holds
+> the code and config it started with, and an editable install does not change that.
+
+> **The PyPI name is `echo-mem`, not `echo-memory`.** That name belongs to an unrelated
+> hosted product. The import package and the CLI are both `echo_memory` / `echo-memory`;
+> only the distribution name differs.
+
+## Usage
+
+```bash
+echo-memory status                 # what each scope holds, and which agents have written
+echo-memory health                 # a score, what is weak, and what to do about it
+echo-memory dashboard --serve      # the graph, in a browser, localhost only
+
+echo-memory why <fact_id>          # the full audit trail for one fact
+echo-memory recall "<question>"    # query the store from a terminal
+echo-memory export                 # everything, as JSON
+
+echo-memory install --for cursor   # wire one client, project scoped
+echo-memory adopt                  # wire every MCP client on the machine, each with its own id
+
+echo-memory eval                   # retrieval quality against your own store
+echo-memory eval --context         # what a recall costs against injecting everything
+echo-memory eval --context --sweep # the same, as a curve across corpus size
+echo-memory calibrate              # is entity resolution trustworthy on your data
+echo-memory benchmark              # write, query and digest latency
+```
+
+### The six MCP tools
+
+| Tool | What it does |
+|---|---|
+| `write_episode` | Store entities and the facts connecting them. No model call. |
+| `query_memory` | Hybrid vector and full text retrieval, fused by reciprocal rank. |
+| `record_recall_save` | Mark that a recalled fact saved re explaining something. Refuses a fact no read returned. |
+| `get_audit_log` | Every change to memory, with a plain language reason. |
+| `pending_documents` | Memory files this project wrote that the graph has not heard about. |
+| `mark_ingested` | Close one of those out. |
+
+## What you get
+
+**A graph, not a list.** Entities are nodes and a fact is an edge between two of them.
+Two sessions that never knew about each other resolve onto the same entity by name, so
+the second inherits what the first learned.
+
+**Bounded retrieval.** Old, rarely read memory consolidates into higher level summaries
+over time. Nothing is discarded; what changes is how much a query has to walk.
+
+**Provenance on every fact.** Who wrote it, which tool, which project, when, and which
+reads returned it. A superseded fact is never deleted. It stops being drawn and stays
+reachable with its history.
+
+**Causal typing.** Edges can be tagged `caused_by`, `led_to`, `blocked_by`,
+`contradicts`, set by the agent's own read of the conversation rather than inferred
+statistically.
+
+**No inference on the write path.** Extraction happens in the calling agent, so storing
+a memory invokes no model on the server. The cost moved rather than vanished: the agent
+has to arrive with entities and facts already extracted, which is what the
+[tool contract](docs/DEVELOPMENT.md) spells out. The comparison that makes this matter is
+Zep/Graphiti, the closest architectural match, whose own description of ingestion is that
+"every episode triggers multiple LLM calls" and that "write cost scales with volume".
+
+The obvious reply is that cheap writes are cheap because they do less, and that reply is
+correct on the mechanism. [`docs/WRITE-COST.md`](docs/WRITE-COST.md) answers it properly,
+including the two measured costs of the choice: the Stop gate fired seven times and
+produced one fact, and a write touching an ambiguous entity is deferred while the call
+returns as though it succeeded.
+
+**Any MCP client.** A coding assistant, a chatbot, an ops agent, or something built in
+house. Coding agents are where this is proven, not what it is limited to.
+
+## Numbers, and how they were taken
+
+Every figure comes from this repository or a live store, on a date, with the command that
+reproduces it on yours. The corpus is small and the noise floor is stated, because a
+difference nobody sized is not a result.
+
+| Measure | Value | Reproduce |
+|---|---|---|
+| Context per recall vs injecting everything | **96.7% less**, hit@10 0.872 over 1,190 questions | `echo-memory eval --context` |
+| 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` |
+| LoCoMo retrieval, 1,982 questions, 5,882 turns | recall@10 **0.601**, hit@10 0.658, MRR 0.460 | `scripts/locomo-bench.py` |
+| LongMemEval retrieval, 90 questions, 15 per type | session@10 **0.940**, turn@10 0.727 | `scripts/longmemeval-bench.py --per-type 15` |
+| Server side model calls per write | **0** | `echo-memory benchmark` |
+| Write, query, digest latency (median) | 15ms, 8ms, 1ms | `echo-memory benchmark` |
+| Entity resolution AUC | 0.666, 95% CI [0.421, 0.881] | `echo-memory calibrate` |
+
+That last row is the one that went the wrong way, and it is here on purpose. The interval
+includes chance, so the unattended merge is switched off: at the automatic bar precision
+was 50% over two reviewed pairs, and the audit log showed that path had fired once in the
+system's entire history. A near match is now offered for confirmation instead.
+
+The LoCoMo row is retrieval, not QA accuracy. Published LoCoMo results have a model write
+an answer and a second model judge it; this asks only whether the turn holding the answer
+came back, which is a ceiling on QA accuracy rather than a substitute for it, and is not
+comparable to anybody's published QA figure. It also feeds raw dialogue turns, which skips
+the extraction step this design pushes to the calling agent, so it is a floor as well as a
+ceiling. The worst row, multi hop at recall@1 0.099, is in
+[`docs/BENCHMARKS.md`](docs/BENCHMARKS.md) with the rest.
+
+The context saving is measured against a specific baseline, stated so it cannot be read
+as more than it is. Not "no memory at all", which is however long a human spends re
+explaining and is unmeasurable. It is the thing people do instead: keep the project's
+notes in one file and paste the whole file. On that store the file is 325 facts, about
+41,838 tokens; a recall returned 1,372 on average. The hit rate belongs beside it, because
+a recall that returned nothing would score 100%.
+
+## The graph
+
+Memory is a graph, not a list of notes. Entities are nodes; a fact is an **edge** between
+two of them. That is the whole data model, and everything else follows from it.
+
+![The memory graph](docs/images/graph-overview.png)
+
+Three projects here. `checkout-api`, `mobile-app` and `data-pipeline` were recorded in
+separate sessions and never told about each other, yet the picture already separates them,
+because separation is a property of the edges rather than a label anyone applied.
+
+**Clusters come from structure.** Densely connected facts are grouped by label propagation
+over the edges, and each cluster is named after its most connected node. That is why
+`data-pipeline` sits apart: nothing it knows touches payments. It is also why
+`checkout-api` and `mobile-app` share a cluster despite being different codebases. They
+genuinely share an idea, and the graph found it rather than being told.
+
+**Components are the stronger claim.** Two nodes in different components have no path
+between them at all, which is the strongest statement this graph can make that two
+memories are unrelated.
+
+### Click a node: everything it takes part in
+
+![A node selected](docs/images/graph-node-selected.png)
+
+`idempotency keys` is the largest node here and nobody made it large: seventeen facts from
+several services resolved onto one entity by name. The panel lists every one, with which
+agent wrote it and when.
+
+### Click a link: why memory believes it
+
+![A fact selected](docs/images/graph-fact-selected.png)
+
+Not a tooltip. Who wrote the fact, in which project, when, and how each of its entities
+resolved. `echo-memory why <fact_id>` prints the same trail in a terminal.
+
+### Seeing your own
+
+```bash
+echo-memory dashboard --serve --open
+```
+
+The images above come from a synthetic dataset (`scripts/demo-seed.py`) rather than a real
+store, for the obvious reason: a real memory graph is full of hostnames, account numbers
+and client names.
+
+## Wiring more than one tool
+
+**Give each client its own `ECHO_MEMORY_AGENT_ID`.** Cursor should say `cursor`, Claude
+Desktop `claude-desktop`. Memory is shared either way, but a fact records which tool
+learned it, and two tools claiming the same id makes cross tool recall impossible to see
+afterwards.
+
+```bash
+echo-memory adopt                  # every MCP client on the machine, each with its own id
+echo-memory install [path]         # one project: MCP config plus a skill, committed with the code
+```
+
+`adopt` shows the diff before writing anything. For an agent that does not speak MCP, see
+[`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md).
+
+## Is the graph in good shape?
+
+```bash
+echo-memory health
+```
+
+A score, what is strong, what needs attention, and what to do about each, including what
+recall has cost: how often memory was read, how often a read returned anything, roughly
+how many tokens were injected, and how many saves those reads produced. Writes were
+counted from the start; reads were not counted at all, so nothing could answer whether
+recall earns what it costs. It exists to be run when you have no question, because a store
+can look healthy by every other number while most of its facts came from a bulk import,
+the last real write was a week ago, and only one of several wired agents has ever written
+anything. `--json` for machine readable output.
+
+Nothing in it is gated. The paid plan sells hosting; diagnostics about your own data are
+not a thing to withhold from the person whose data it is.
+
+## Architecture
+
+**Storage** PostgreSQL with `pgvector` and Apache AGE, from a single local agent up to an
+organisation wide shared graph, with no forced migration later. The novel work is the
+memory structure and the read/write algorithm on top of it, not a new database engine.
+
+**Retrieval** Hybrid vector and full text search fused by reciprocal rank in v1a.
+Personalised PageRank via `networkx` lands in v1b for multi hop associative retrieval.
+
+**Interface** [Model Context Protocol](https://modelcontextprotocol.io), so any compliant
+agent reads and writes the same graph.
+
+## Status
+
+Early and staged, on purpose. See [`docs/designs/`](docs/designs/) for the architecture
+and the v1a to v1b plan.
+
+| | |
+|---|---|
+| **v1a, built** | Basic recall. Six MCP tools, thirty CLI commands, on PyPI and in the MCP registry. |
+| **v1b, gated** | Causal typing and multi hop retrieval. 187 questions no single fact answers score MRR 0.212 today; the number to beat exists before the feature does. |
+| **v1.1, planned** | Organisation wide tenancy: per agent, per team, or org wide graphs. |
+
+The validated wedge driving v1a is memory shared across coding agents, which is the
+author's own daily pain and the case with the most evidence behind it. Everything else is
+the target this architecture is built toward.
+
+## Hosted
+
+Running it yourself is free forever under Apache 2.0, with no account and no feature held
+back. [app.echo-mem.com](https://app.echo-mem.com) runs the database for you at $99 a
+month if you would rather not.
+
+<details>
+<summary>Contributing</summary>
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md). Issues and pull requests welcome; please read the
+design docs first so proposals fit the staged build plan. A first pull request is asked to
+sign the [Contributor License Agreement](CLA.md), once, in the PR thread.
+
+The most useful contribution is a measurement that disagrees with one of the numbers
+above. Run `echo-memory eval`, `calibrate` or `benchmark` on your own store and open an
+issue with the output.
+
+</details>
+
+## License
+
+Apache License 2.0. See [`LICENSE`](LICENSE).
+
+<!-- The MCP registry proves you own a PyPI package by finding this line in the
+     package's own description. It has to survive into the built distribution,
+     which is why it lives in the README rather than in a workflow. -->
+mcp-name: io.github.ayushcodes10/echo-mem

echo_mem-0.4.1/README.md

@@ -0,0 +1,293 @@
+# Echo Memory
+
+[![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)
+[![PyPI](https://img.shields.io/pypi/v/echo-mem)](https://pypi.org/project/echo-mem/)
+[![Python](https://img.shields.io/pypi/pyversions/echo-mem)](https://pypi.org/project/echo-mem/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+
+**Shared memory for AI agents, as a graph in your own database.** What Claude Code learns,
+Cursor and Codex can recall. Every fact records who wrote it and when, and the server
+never calls a model to store one.
+
+> Your agents start every session from zero. The usual fix is a notes file you paste into
+> context, which grows until it is mostly irrelevant to whatever you are asking. Echo
+> Memory is the other shape: facts connected to each other, and a query that returns the
+> few that matter. On the author's own store that is **96.7% less context** for the same
+> answer, with the answer still present 87.2% of the time across 1,190 questions.
+
+```
+write_episode                          query_memory
+  billing ──uses──▸ Razorpay             "how do we take payments"
+    │ written by claude-code               ▸ billing uses Razorpay, not Stripe
+    │ supersedes ──▸ Stripe                  written by claude-code, 3 days ago
+    └ no model invoked                     ▸ 1,372 tokens, not 41,838
+```
+
+## Install
+
+**Requires:** Python 3.11+ and Docker (for the database).
+
+```bash
+pipx install echo-mem
+echo-memory quickstart
+```
+
+`quickstart` starts the database, applies the schema, and prints the `claude mcp add`
+line that registers it, filled in with the port it actually used. The Postgres image is
+published, so nothing compiles.
+
+Or use the hosted service and run no database at all:
+
+```bash
+pipx install echo-mem
+echo-memory connect <key>          # a key from https://app.echo-mem.com
+```
+
+Then once per machine, so an agent knows *when* to record and recall rather than only
+that the tools exist:
+
+```bash
+echo-memory install --global
+```
+
+> **Restart your client afterwards.** An MCP server is a long lived process that holds
+> the code and config it started with, and an editable install does not change that.
+
+> **The PyPI name is `echo-mem`, not `echo-memory`.** That name belongs to an unrelated
+> hosted product. The import package and the CLI are both `echo_memory` / `echo-memory`;
+> only the distribution name differs.
+
+## Usage
+
+```bash
+echo-memory status                 # what each scope holds, and which agents have written
+echo-memory health                 # a score, what is weak, and what to do about it
+echo-memory dashboard --serve      # the graph, in a browser, localhost only
+
+echo-memory why <fact_id>          # the full audit trail for one fact
+echo-memory recall "<question>"    # query the store from a terminal
+echo-memory export                 # everything, as JSON
+
+echo-memory install --for cursor   # wire one client, project scoped
+echo-memory adopt                  # wire every MCP client on the machine, each with its own id
+
+echo-memory eval                   # retrieval quality against your own store
+echo-memory eval --context         # what a recall costs against injecting everything
+echo-memory eval --context --sweep # the same, as a curve across corpus size
+echo-memory calibrate              # is entity resolution trustworthy on your data
+echo-memory benchmark              # write, query and digest latency
+```
+
+### The six MCP tools
+
+| Tool | What it does |
+|---|---|
+| `write_episode` | Store entities and the facts connecting them. No model call. |
+| `query_memory` | Hybrid vector and full text retrieval, fused by reciprocal rank. |
+| `record_recall_save` | Mark that a recalled fact saved re explaining something. Refuses a fact no read returned. |
+| `get_audit_log` | Every change to memory, with a plain language reason. |
+| `pending_documents` | Memory files this project wrote that the graph has not heard about. |
+| `mark_ingested` | Close one of those out. |
+
+## What you get
+
+**A graph, not a list.** Entities are nodes and a fact is an edge between two of them.
+Two sessions that never knew about each other resolve onto the same entity by name, so
+the second inherits what the first learned.
+
+**Bounded retrieval.** Old, rarely read memory consolidates into higher level summaries
+over time. Nothing is discarded; what changes is how much a query has to walk.
+
+**Provenance on every fact.** Who wrote it, which tool, which project, when, and which
+reads returned it. A superseded fact is never deleted. It stops being drawn and stays
+reachable with its history.
+
+**Causal typing.** Edges can be tagged `caused_by`, `led_to`, `blocked_by`,
+`contradicts`, set by the agent's own read of the conversation rather than inferred
+statistically.
+
+**No inference on the write path.** Extraction happens in the calling agent, so storing
+a memory invokes no model on the server. The cost moved rather than vanished: the agent
+has to arrive with entities and facts already extracted, which is what the
+[tool contract](docs/DEVELOPMENT.md) spells out. The comparison that makes this matter is
+Zep/Graphiti, the closest architectural match, whose own description of ingestion is that
+"every episode triggers multiple LLM calls" and that "write cost scales with volume".
+
+The obvious reply is that cheap writes are cheap because they do less, and that reply is
+correct on the mechanism. [`docs/WRITE-COST.md`](docs/WRITE-COST.md) answers it properly,
+including the two measured costs of the choice: the Stop gate fired seven times and
+produced one fact, and a write touching an ambiguous entity is deferred while the call
+returns as though it succeeded.
+
+**Any MCP client.** A coding assistant, a chatbot, an ops agent, or something built in
+house. Coding agents are where this is proven, not what it is limited to.
+
+## Numbers, and how they were taken
+
+Every figure comes from this repository or a live store, on a date, with the command that
+reproduces it on yours. The corpus is small and the noise floor is stated, because a
+difference nobody sized is not a result.
+
+| Measure | Value | Reproduce |
+|---|---|---|
+| Context per recall vs injecting everything | **96.7% less**, hit@10 0.872 over 1,190 questions | `echo-memory eval --context` |
+| 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` |
+| LoCoMo retrieval, 1,982 questions, 5,882 turns | recall@10 **0.601**, hit@10 0.658, MRR 0.460 | `scripts/locomo-bench.py` |
+| LongMemEval retrieval, 90 questions, 15 per type | session@10 **0.940**, turn@10 0.727 | `scripts/longmemeval-bench.py --per-type 15` |
+| Server side model calls per write | **0** | `echo-memory benchmark` |
+| Write, query, digest latency (median) | 15ms, 8ms, 1ms | `echo-memory benchmark` |
+| Entity resolution AUC | 0.666, 95% CI [0.421, 0.881] | `echo-memory calibrate` |
+
+That last row is the one that went the wrong way, and it is here on purpose. The interval
+includes chance, so the unattended merge is switched off: at the automatic bar precision
+was 50% over two reviewed pairs, and the audit log showed that path had fired once in the
+system's entire history. A near match is now offered for confirmation instead.
+
+The LoCoMo row is retrieval, not QA accuracy. Published LoCoMo results have a model write
+an answer and a second model judge it; this asks only whether the turn holding the answer
+came back, which is a ceiling on QA accuracy rather than a substitute for it, and is not
+comparable to anybody's published QA figure. It also feeds raw dialogue turns, which skips
+the extraction step this design pushes to the calling agent, so it is a floor as well as a
+ceiling. The worst row, multi hop at recall@1 0.099, is in
+[`docs/BENCHMARKS.md`](docs/BENCHMARKS.md) with the rest.
+
+The context saving is measured against a specific baseline, stated so it cannot be read
+as more than it is. Not "no memory at all", which is however long a human spends re
+explaining and is unmeasurable. It is the thing people do instead: keep the project's
+notes in one file and paste the whole file. On that store the file is 325 facts, about
+41,838 tokens; a recall returned 1,372 on average. The hit rate belongs beside it, because
+a recall that returned nothing would score 100%.
+
+## The graph
+
+Memory is a graph, not a list of notes. Entities are nodes; a fact is an **edge** between
+two of them. That is the whole data model, and everything else follows from it.
+
+![The memory graph](docs/images/graph-overview.png)
+
+Three projects here. `checkout-api`, `mobile-app` and `data-pipeline` were recorded in
+separate sessions and never told about each other, yet the picture already separates them,
+because separation is a property of the edges rather than a label anyone applied.
+
+**Clusters come from structure.** Densely connected facts are grouped by label propagation
+over the edges, and each cluster is named after its most connected node. That is why
+`data-pipeline` sits apart: nothing it knows touches payments. It is also why
+`checkout-api` and `mobile-app` share a cluster despite being different codebases. They
+genuinely share an idea, and the graph found it rather than being told.
+
+**Components are the stronger claim.** Two nodes in different components have no path
+between them at all, which is the strongest statement this graph can make that two
+memories are unrelated.
+
+### Click a node: everything it takes part in
+
+![A node selected](docs/images/graph-node-selected.png)
+
+`idempotency keys` is the largest node here and nobody made it large: seventeen facts from
+several services resolved onto one entity by name. The panel lists every one, with which
+agent wrote it and when.
+
+### Click a link: why memory believes it
+
+![A fact selected](docs/images/graph-fact-selected.png)
+
+Not a tooltip. Who wrote the fact, in which project, when, and how each of its entities
+resolved. `echo-memory why <fact_id>` prints the same trail in a terminal.
+
+### Seeing your own
+
+```bash
+echo-memory dashboard --serve --open
+```
+
+The images above come from a synthetic dataset (`scripts/demo-seed.py`) rather than a real
+store, for the obvious reason: a real memory graph is full of hostnames, account numbers
+and client names.
+
+## Wiring more than one tool
+
+**Give each client its own `ECHO_MEMORY_AGENT_ID`.** Cursor should say `cursor`, Claude
+Desktop `claude-desktop`. Memory is shared either way, but a fact records which tool
+learned it, and two tools claiming the same id makes cross tool recall impossible to see
+afterwards.
+
+```bash
+echo-memory adopt                  # every MCP client on the machine, each with its own id
+echo-memory install [path]         # one project: MCP config plus a skill, committed with the code
+```
+
+`adopt` shows the diff before writing anything. For an agent that does not speak MCP, see
+[`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md).
+
+## Is the graph in good shape?
+
+```bash
+echo-memory health
+```
+
+A score, what is strong, what needs attention, and what to do about each, including what
+recall has cost: how often memory was read, how often a read returned anything, roughly
+how many tokens were injected, and how many saves those reads produced. Writes were
+counted from the start; reads were not counted at all, so nothing could answer whether
+recall earns what it costs. It exists to be run when you have no question, because a store
+can look healthy by every other number while most of its facts came from a bulk import,
+the last real write was a week ago, and only one of several wired agents has ever written
+anything. `--json` for machine readable output.
+
+Nothing in it is gated. The paid plan sells hosting; diagnostics about your own data are
+not a thing to withhold from the person whose data it is.
+
+## Architecture
+
+**Storage** PostgreSQL with `pgvector` and Apache AGE, from a single local agent up to an
+organisation wide shared graph, with no forced migration later. The novel work is the
+memory structure and the read/write algorithm on top of it, not a new database engine.
+
+**Retrieval** Hybrid vector and full text search fused by reciprocal rank in v1a.
+Personalised PageRank via `networkx` lands in v1b for multi hop associative retrieval.
+
+**Interface** [Model Context Protocol](https://modelcontextprotocol.io), so any compliant
+agent reads and writes the same graph.
+
+## Status
+
+Early and staged, on purpose. See [`docs/designs/`](docs/designs/) for the architecture
+and the v1a to v1b plan.
+
+| | |
+|---|---|
+| **v1a, built** | Basic recall. Six MCP tools, thirty CLI commands, on PyPI and in the MCP registry. |
+| **v1b, gated** | Causal typing and multi hop retrieval. 187 questions no single fact answers score MRR 0.212 today; the number to beat exists before the feature does. |
+| **v1.1, planned** | Organisation wide tenancy: per agent, per team, or org wide graphs. |
+
+The validated wedge driving v1a is memory shared across coding agents, which is the
+author's own daily pain and the case with the most evidence behind it. Everything else is
+the target this architecture is built toward.
+
+## Hosted
+
+Running it yourself is free forever under Apache 2.0, with no account and no feature held
+back. [app.echo-mem.com](https://app.echo-mem.com) runs the database for you at $99 a
+month if you would rather not.
+
+<details>
+<summary>Contributing</summary>
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md). Issues and pull requests welcome; please read the
+design docs first so proposals fit the staged build plan. A first pull request is asked to
+sign the [Contributor License Agreement](CLA.md), once, in the PR thread.
+
+The most useful contribution is a measurement that disagrees with one of the numbers
+above. Run `echo-memory eval`, `calibrate` or `benchmark` on your own store and open an
+issue with the output.
+
+</details>
+
+## License
+
+Apache License 2.0. See [`LICENSE`](LICENSE).
+
+<!-- The MCP registry proves you own a PyPI package by finding this line in the
+     package's own description. It has to survive into the built distribution,
+     which is why it lives in the README rather than in a workflow. -->
+mcp-name: io.github.ayushcodes10/echo-mem

{echo_mem-0.3.0 → echo_mem-0.4.1}/pyproject.toml

@@ -6,7 +6,7 @@
 # (`-m echo_memory.server`) and every existing install reference it, and
 # renaming the module would break live configuration to fix a cosmetic mismatch.
 name = "echo-mem"
-version = "0.3.0"
+version = "0.4.1"
 description = "A long-horizon memory architecture for AI agents"
 readme = "README.md"
 license = "Apache-2.0"