aether-cache 0.1.0__tar.gz

aether_cache-0.1.0/PKG-INFO

@@ -0,0 +1,353 @@
+Metadata-Version: 2.4
+Name: aether-cache
+Version: 0.1.0
+Summary: Shared memory for AI coding tools that stays true to your code.
+Author: Anish Chugh
+Project-URL: Homepage, https://github.com/anishchugh05/Aether-Cache-Redis-Compatible-Vector-Store
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.2
+Requires-Dist: fastembed>=0.3
+Requires-Dist: redis>=5.0
+
+[![progress-banner](https://backend.codecrafters.io/progress/redis/f43a7cd3-11e6-45dc-a8ba-9d6690c73ac0)](https://app.codecrafters.io/users/anishchugh05?r=2qF)
+
+# Aether Cache
+
+**Shared memory for AI coding tools that stays true to your code.**
+
+Claude Code, Cursor, and other AI tools each forget your project between sessions, and when they do remember things,
+nothing checks whether those memories are still correct. Aether Cache gives every tool one shared, local memory, and keeps
+it honest:
+
+- **Memories go stale when the code changes.** Each memory is linked to the files it's about, with a snapshot of their
+  git content hash. When `docker-compose.yml` changes, the memory about it is retired automatically instead of being
+  fed to your AI forever.
+- **Contradictions get replaced, not hoarded.** "We migrated to MySQL" retires "we use Postgres" instead of sitting
+  next to it and confusing the model. Near-identical repeats are merged.
+- **Every memory can explain itself.** Which tool and session saved it, which file versions it was based on, and every
+  change since: created, seen again, went stale, confirmed, replaced.
+- **It works with the files you already use.** Current memories sync into a managed section of `AGENTS.md` and
+  `CLAUDE.md`, so they're committed, reviewed in PRs, and visible to teammates who don't run Aether Cache.
+
+It runs entirely on your machine, on top of a database engine I wrote from scratch.
+
+## Not a Redis clone
+
+Aether Cache started as a from-scratch rebuild of Redis in Java, then kept going. Every layer here is written from
+scratch, and each one does something the layer beneath it can't:
+
+| Layer | What it adds |
+|---|---|
+| **MCP server** | Claude Code, Cursor, and any MCP tool share one memory |
+| **Git awareness** | Memories retire themselves when the code they describe changes |
+| **Memory layer** | Status, provenance, full history, duplicate merging, and conflict review, inside the engine |
+| **HNSW vector index** | Semantic search: 99.4% recall at 0.84 ms on 100K vectors, 22× faster than exact search |
+| **Redis-compatible engine** | RESP protocol, 50+ commands, replication, transactions, and crash-safe persistence (0 acknowledged writes lost across 1,039,890 writes and 8 `kill -9` crashes), at 88–93% of real Redis's throughput |
+
+The bottom layer alone is a working Redis: `redis-cli`, `redis-benchmark`, and `redis-py` talk to it unchanged. The
+memory layer, git awareness, and MCP server are things Redis doesn't do at all.
+
+```
+Claude Code ─┐                       ┌─────────────────────────────────────────────┐
+Cursor ──────┼─ MCP ─► aether_cache ─┼─ RESP ─► Java engine (Main.java)            │
+other tools ─┘   (Python: embeddings,│          memories, HNSW vector index,       │
+                  git hashing, sync) │          history, append-only file on disk  │
+                                     └─────────────────────────────────────────────┘
+```
+
+## What it looks like
+
+A memory linked to a file, the file changes, and the next lookup catches it:
+
+```
+> remember("The database runs Postgres via docker compose", files=["docker-compose.yml"])
+Saved as m1.
+
+        ... someone edits docker-compose.yml ...
+
+> recall("database setup")
+These memories were just retired because files they depend on changed. If one is still true,
+call confirm_memory; if it's wrong, save the corrected fact with remember:
+[m1] "The database runs Postgres via docker compose" is now marked outdated: docker-compose.yml changed.
+
+> confirm_memory("m1")        # still true, so re-link it to the new version of the file
+Confirmed m1; it's active again and linked to the current file versions.
+
+> explain_memory("m1")
+m1: "The database runs Postgres via docker compose"
+status: active, project: demo
+saved by: claude-code (session eea54b5c)
+linked files: docker-compose.yml@02ea346...
+history:
+  19:16  created: by claude-code (session eea54b5c), linked to docker-compose.yml@87da641...
+  19:16  active -> stale: docker-compose.yml changed since this was saved
+  19:16  re-linked: to docker-compose.yml@02ea346... (confirmed still true)
+  19:16  stale -> active: confirmed still true
+```
+
+A newer fact replacing an older one:
+
+```
+> remember("The API timeout was raised to 60 seconds")
+Saved as m3.
+Related existing memories:
+[m1] (similarity 0.58) The API timeout is 30 seconds
+If m3 makes any of these no longer true, call replace_memory(old_id, "m3"). Otherwise do nothing.
+
+> replace_memory("m1", "m3")
+m1 retired; m3 replaces it.
+```
+
+## Quick start
+
+You need **Java 11+** (`brew install openjdk@21` on macOS, or [adoptium.net](https://adoptium.net)) and
+[**uv**](https://docs.astral.sh/uv/) (`curl -LsSf https://astral.sh/uv/install.sh | sh`), which also takes care of
+Python for you. Then:
+
+```sh
+uv tool install git+https://github.com/anishchugh05/Aether-Cache-Redis-Compatible-Vector-Store
+aether-cache setup
+```
+
+`setup` starts the engine in the background, downloads the embedding model once (about 90 MB), and connects every
+supported AI tool it finds on your machine: **Claude Code, Cursor, and Codex**. That's it. Open your AI tool in any git
+repo and try:
+
+> Remember that our tests need DOCKER_HOST set. It depends on docker-compose.yml.
+
+Then start a new session and ask how to run the tests.
+
+Memories are kept per project (the git repo's folder name), so projects never mix. Everything stays on your machine:
+the engine only accepts connections from it, and your memories live in `~/.aether-cache`.
+
+| Command | What it does |
+|---|---|
+| `aether-cache setup` | One-time setup: engine, model, and AI tools |
+| `aether-cache status` | Is it running, and what's in this project's memory |
+| `aether-cache doctor` | Checks everything and tells you how to fix what's wrong |
+| `aether-cache list` / `recall "query"` / `explain m1` | Look at memories from the terminal |
+| `aether-cache sync` | Writes current memories into `AGENTS.md` / `CLAUDE.md` |
+| `aether-cache connect cursor` | Connects one tool (`--print` shows config for any other MCP tool) |
+| `aether-cache start` / `stop` | Runs or stops the engine (it also starts on its own when a tool needs it) |
+
+If `aether-cache` isn't found after installing, run `uv tool update-shell` and open a new terminal. Port 7380 taken?
+Set `AETHER_PORT` and run `setup` again. To uninstall: `aether-cache stop && uv tool uninstall aether-cache`.
+
+## Tools the AI can call
+
+| Tool | What it does |
+|---|---|
+| `remember(fact, files?)` | Saves a durable fact, optionally linked to files. Merges near-identical repeats and shows related memories so the AI can decide whether the new fact replaces one. |
+| `recall(query, limit?)` | Searches the project's memories by meaning. Checks linked files first, so it never returns a memory whose code changed underneath it. |
+| `explain_memory(id)` | Where a memory came from and its full history. |
+| `replace_memory(old, new)` | Retires an older memory that a newer one makes untrue. |
+| `mark_outdated(id, reason)` | Retires a memory that turned out to be wrong. |
+| `confirm_memory(id)` | Brings back a memory that's still true after its files changed, re-linked to the current versions. |
+| `check_stale()` | Runs the file check on demand. |
+| `list_conflicts()` / `resolve_conflict(...)` | Reviews pairs of very similar memories that may contradict each other. |
+| `sync_to_files()` | Writes current memories into `AGENTS.md` / `CLAUDE.md` (also: `aether-cache sync`). |
+
+## Design decisions, and what the measurements said
+
+### Similarity can't detect contradictions, so the AI judges
+
+The first version flagged a new memory as a possible contradiction when it was similar to an existing one. Calibrating
+with real `all-MiniLM-L6-v2` embeddings showed that can't work:
+
+| Pair | Kind | Similarity |
+|---|---|---|
+| "we use Postgres" / "the database is Postgres" | duplicate | 0.73 |
+| "tests need DOCKER_HOST set" / "you have to set DOCKER_HOST before running tests" | duplicate | 0.92 |
+| "we use Postgres" / "we migrated to MySQL" | **contradiction** | **0.30** |
+| "API timeout is 30 seconds" / "API timeout is 60 seconds" | **contradiction** | **0.94** |
+| "tests need DOCKER_HOST set" / "integration tests need a running Redis" | related, both true | 0.34 |
+
+Duplicates scored 0.73 to 0.92 and contradictions 0.30 to 0.94, so no threshold separates them. A threshold low enough
+to merge real duplicates would silently merge "timeout is 30s" with "timeout is 60s", the worst bug this product could
+have. So the engine only auto-merges near-identical text (similarity ≥ 0.97). For everything else, embeddings *find*
+the related memories and the AI, which already understands the sentences, *decides* whether one replaces another.
+
+### Staleness compares file contents, not commits
+
+Each linked file is stored as `path@<git blob hash>`, computed with `git hash-object`. Comparing contents rather than
+commit ids catches uncommitted edits, ignores commits that didn't touch the file, and needs no git hooks: `recall`
+re-hashes the handful of linked files before every search.
+
+### Memories never mutate silently
+
+Every change is a logged event with a timestamp and a reason. The engine logs each memory *with* the id and timestamp
+it assigned, so replaying the log after a restart rebuilds the exact same memories and histories, down to the
+millisecond, instead of minting new ones.
+
+## The engine underneath
+
+A Redis-compatible server written from scratch in Java. It speaks RESP, so `redis-cli`, `redis-benchmark`, and
+`redis-py` work with it unchanged. The core was built by completing every stage and extension of the
+[CodeCrafters "Build Your Own Redis"](https://codecrafters.io/challenges/redis) challenge; the vector index,
+persistence hardening, and the memory layer are my own additions.
+
+### Throughput vs. official Redis
+
+`redis-benchmark -t set,get`, 100K requests, 50 parallel clients, 3-byte values, same machine:
+
+| | Aether Cache | Redis 8.10.2 | Aether Cache as % of Redis |
+|---|---|---|---|
+| SET | 205.8K ops/sec | 233.6K ops/sec | 88% |
+| GET | 225.7K ops/sec | 242.7K ops/sec | 93% |
+| p50 latency | 0.119 ms | 0.111 ms | |
+| p99 latency (SET / GET) | 0.375 / 0.231 ms | 0.359 / 0.159 ms | |
+| max latency (SET) | 19.7 ms | 1.3 ms | JVM GC / JIT pauses |
+
+Typical latency is on par with Redis. The gap is in worst-case latency, from JVM garbage collection and JIT warm-up,
+which Redis (written in C) doesn't have.
+
+### HNSW vector search vs. exact search
+
+100,000 AG News headlines embedded with `all-MiniLM-L6-v2` (384 dimensions, cosine similarity), 500 held-out queries,
+k = 10. Recall is measured against exact brute-force search on the same data.
+
+| Mode | Recall@10 | p50 latency | p99 latency |
+|---|---|---|---|
+| Exact (brute force) | 1.000 | 18.58 ms | 20.52 ms |
+| HNSW, ef=10 | 0.905 | 0.49 ms | 1.38 ms |
+| HNSW, ef=20 | 0.951 | 0.52 ms | 0.73 ms |
+| HNSW, ef=50 | 0.985 | 0.66 ms | 0.89 ms |
+| **HNSW, ef=100** | **0.994** | **0.84 ms** | **1.41 ms** |
+| HNSW, ef=200 | 0.998 | 1.24 ms | 2.19 ms |
+
+At ef=100, HNSW returns 99.4% of the true top-10 about **22× faster** than exact search. Building the index for 100K
+vectors took 136 seconds (M=16, M0=32, efConstruction=200). Latencies are measured from the Python client, so they
+include network and client overhead. Full setup and raw numbers: `results.json`.
+
+**How it works:** each vector links to its nearest neighbors in a layered graph. A search starts on a sparse top layer
+of long-range links, hops greedily toward the query, drops down a layer at a time, and finishes with a best-first search
+on the bottom layer that keeps the `ef` best candidates. Neighbor selection uses the diversity heuristic from the HNSW
+paper (prefer neighbors in different directions over near-duplicates), which is what keeps recall high.
+
+**Filtered search:** HNSW doesn't know about memory status, so searches over-fetch candidates, drop the ones that don't
+match (stale or superseded), widen the search if too few survive, and fall back to an exact scan if needed. In a test
+with 2,000 memories where only 2% were active, filtered searches returned exactly the correct top 10 on 30/30 queries.
+The catch: at that selectivity, the exact fallback runs most of the time, which is the known weak spot of
+post-filtering on graph indexes.
+
+### Crash safety
+
+Every write goes to an append-only file (AOF) that is replayed on startup.
+
+**`kill -9` crash test** (`crash_test.py`): a client writes as fast as it can, the server is killed at a random moment,
+restarted, and every write the server acknowledged is checked.
+
+| fsync policy | Crashes | Acknowledged writes | Lost |
+|---|---|---|---|
+| `everysec` | 5 | 757,295 | **0** |
+| `always` | 3 | 282,595 | **0** |
+
+Recovery took 0.6 seconds per restart, replaying up to ~185K writes.
+
+**Torn writes:** a machine crash can cut the last write off halfway. The first version refused to start on such a file;
+now replay stops at the last complete command, trims the partial one, and starts normally with all earlier data intact.
+
+**Cost of each fsync policy** (SET throughput, 50 clients):
+
+| Policy | Throughput | p50 latency |
+|---|---|---|
+| `always` (sync every write) | 42.9K/sec | 1.159 ms |
+| `everysec` (sync once a second) | 113.9K/sec | 0.103 ms |
+| `no` (let the OS decide) | 118.8K/sec | 0.103 ms |
+
+`everysec` is 2.7× faster than `always` and within 4% of `no`, which is why it's the sensible default. On macOS, `fsync`
+doesn't force the SSD's own cache to flush, so `always` looks cheaper here than it would on a Linux server.
+
+### Full command list
+
+- **Memory:**
+  - `MEM.ADD`, `MEM.GET`, `MEM.SEARCH` (with `STATUS` filter), `MEM.STATUS`, `MEM.WHY`, `MEM.LIST`
+  - `MEM.FILES`, `MEM.SEEN`, `MEM.CONFLICTS`, `MEM.RESOLVE`
+- **Vectors:** `VADD`, `VSEARCH` (HNSW, tunable `EF`, `EXACT` mode)
+- **Strings:** `GET`, `SET` (`EX` / `PX`), `INCR`, `STRLEN`, `TYPE`, `KEYS *`
+- **Lists:** `RPUSH`, `LPUSH`, `LRANGE`, `LLEN`, `LPOP`, blocking `BLPOP`
+- **Streams:** `XADD` (explicit, partial, and auto IDs), `XRANGE`, `XREAD` (with `BLOCK` and `$`)
+- **Sorted sets:** `ZADD`, `ZRANK`, `ZRANGE`, `ZCARD`, `ZSCORE`, `ZREM`
+- **Bitmaps:** `SETBIT`, `GETBIT`, `BITCOUNT`, `BITOP AND` / `OR` (binary-safe strings)
+- **Geospatial:** `GEOADD`, `GEOPOS`, `GEODIST`, `GEOSEARCH ... FROMLONLAT ... BYRADIUS`
+- **Transactions:** `MULTI`, `EXEC`, `DISCARD`, `WATCH`, `UNWATCH` (optimistic locking via per-key write versions)
+- **Pub/Sub:** `SUBSCRIBE`, `UNSUBSCRIBE`, `PUBLISH`
+- **Replication:**
+  - Master–replica handshake (`PING`, `REPLCONF`, `PSYNC`) and command propagation
+  - `REPLCONF GETACK` offset tracking and `WAIT`
+- **Persistence:** RDB loading; AOF with a manifest, `appendfsync always` / `everysec` / `no`, and torn-write recovery
+- **Auth:** `AUTH`, `ACL WHOAMI` / `GETUSER` / `SETUSER` (SHA-256 password hashes)
+
+### Running the engine on its own
+
+```sh
+java src/main/java/Main.java                                   # port 6379
+java src/main/java/Main.java --bind 127.0.0.1                  # accept connections from this machine only
+java src/main/java/Main.java --port 6380 --replicaof "localhost 6379"
+java src/main/java/Main.java --dir /tmp/data --appendonly yes --appendfsync everysec
+```
+
+### Reproducing the benchmarks
+
+Each benchmark runs against the engine you've started:
+
+```sh
+redis-benchmark -p 6379 -t set,get                 # throughput; also run against redis-server to compare
+python vector_bench.py                             # HNSW recall and latency (start the engine with -Xmx4g)
+python crash_test.py everysec 5                    # kill -9 crash test
+python memory_mcp/calibrate.py                     # embedding similarity calibration
+```
+
+## Related work
+
+Aether Cache is an early, open-source project. These are the production systems in the same space:
+
+- **Vector search in Redis-style stores:**
+  - [Redis 8 vector sets](https://redis.io/docs/latest/develop/data-types/vector-sets/) and
+    [valkey-search](https://github.com/valkey-io/valkey-search) add HNSW vector search to Redis and Valkey.
+  - [hnswlib](https://github.com/nmslib/hnswlib) is the reference HNSW implementation.
+  - [Malkov & Yashunin (2016)](https://arxiv.org/abs/1603.09320) is the paper this index follows.
+- **Memory for AI agents:** [Mem0](https://github.com/mem0ai/mem0), [Zep](https://www.getzep.com/),
+  [Letta](https://github.com/letta-ai/letta), and the
+  [MCP reference memory server](https://github.com/modelcontextprotocol/servers).
+- **Instruction files:** [AGENTS.md](https://agents.md/) and `CLAUDE.md`. Aether Cache syncs into these rather than
+  replacing them.
+
+## Status and limitations
+
+Aether Cache is v1 and early. It works end to end in automated tests and is now being tried in real Claude Code sessions.
+
+**Not done yet:**
+- **A with-memory vs. without-memory evaluation** on real coding tasks, to measure whether it actually reduces
+  re-explaining.
+- **AOF compaction:** the log only grows, and every status change adds a line.
+- **A dashboard** to browse, confirm, and retire memories in the browser.
+
+**Engine limitations:**
+- **Threading:** one OS thread per connection, not an event loop. That's fine for a local tool, but it won't scale to
+  thousands of clients like Redis.
+- **Transactions:** `EXEC` isn't isolated, so other clients' commands can interleave with a transaction's commands.
+- **Vector index:** re-adding a vector updates it without rewiring its graph links, and there's no delete. Retired
+  memories are filtered out, not removed.
+- **Replication:** full resync only, and a new replica assumes the master's dataset is empty.
+- **Smaller gaps:**
+  - `KEYS *` lists only string keys.
+  - `GEOSEARCH` scans every member.
+  - ACL supports only the `default` user.
+  - `HELLO` (RESP3) isn't supported, so clients must use RESP2.
+
+## Project layout
+
+```
+src/main/java/Main.java      the engine (single file, from the CodeCrafters setup)
+aether_cache/                the Python package behind the `aether-cache` command
+  server.py                  MCP server: embeddings, git staleness, AGENTS.md/CLAUDE.md sync
+  engine.py                  finds Java, starts and stops the engine in the background
+  connect.py                 registers Aether Cache with Claude Code, Cursor, and Codex
+  cli.py                     the `aether-cache` command
+  engine/aether-engine.jar   the prebuilt engine (rebuild with `python scripts/build_engine.py`)
+memory_mcp/calibrate.py      similarity calibration for duplicate/contradiction thresholds
+vector_bench.py              HNSW benchmark (writes results.json)
+crash_test.py                kill -9 crash-safety test
+```