aether-cache 0.1.0__py3-none-any.whl

aether_cache/__init__.py

@@ -0,0 +1,3 @@
+"""Aether Cache: shared memory for AI coding tools that stays true to your code."""
+
+__version__ = "0.1.0"

aether_cache/__main__.py

@@ -0,0 +1,5 @@
+"""Lets AI tools launch the server as `python -m aether_cache serve`, which works even when the
+`aether-cache` command isn't on their PATH (common for apps started from the dock or Start menu)."""
+from .cli import main
+
+main()

aether_cache/cli.py

@@ -0,0 +1,240 @@
+"""The `aether-cache` command."""
+import argparse
+import sys
+from collections import Counter
+
+from . import __version__, config, connect, engine
+
+OK, WARN, FAIL = "  ok  ", "  !!  ", " FAIL "
+
+
+def _say(mark: str, text: str) -> None:
+    lines = text.splitlines() or [""]
+    print(f"[{mark}] {lines[0]}")
+    for line in lines[1:]:
+        print(f"         {line}")
+
+
+# ---------- commands ----------
+
+def cmd_setup(args) -> int:
+    print(f"Setting up Aether Cache {__version__}\n")
+    try:
+        java, major = engine.find_java()
+        _say(OK, f"Java {major} ({java})")
+        _say(OK, engine.start())
+    except engine.EngineError as e:
+        _say(FAIL, str(e))
+        print("\nFix that, then run `aether-cache setup` again.")
+        return 1
+
+    if config.FAKE_EMBEDDER:
+        _say(OK, "Embedding model: test mode, nothing to download")
+    else:
+        print("[ .... ] Downloading the embedding model (about 90 MB, only the first time)...", flush=True)
+        try:
+            from .server import embed
+            embed("warm up")
+            _say(OK, f"Embedding model ready ({config.MODEL})")
+        except Exception as e:
+            _say(WARN, f"Couldn't download the embedding model yet: {e}\n"
+                       f"It will be downloaded the first time your AI saves or searches a memory.")
+
+    tools = args.tools or connect.detected()
+    if not tools:
+        _say(WARN, "No supported AI coding tools found (Claude Code, Cursor, Codex).")
+        print("\n" + connect.generic_instructions())
+    failed = []
+    for tool in tools:
+        done, message = connect.CONNECTORS[tool]()
+        _say(OK if done else FAIL, message)
+        if not done:
+            failed.append(tool)
+    if failed:
+        print(f"\nAlmost done: fix the {', '.join(failed)} problem above, then run "
+              f"`aether-cache connect {' '.join(failed)}`.")
+        return 1
+
+    print("\nDone. Open your AI tool in any git repo and try:\n"
+          '  "Remember that our tests need DOCKER_HOST set. It depends on docker-compose.yml."\n'
+          "Then, in a new session:\n"
+          '  "How do I run the tests?"\n'
+          "\nCheck on things any time with `aether-cache status`.")
+    return 0
+
+
+def cmd_start(args) -> int:
+    try:
+        print(engine.start())
+        return 0
+    except engine.EngineError as e:
+        print(e)
+        return 1
+
+
+def cmd_stop(args) -> int:
+    print(engine.stop())
+    return 0
+
+
+def cmd_status(args) -> int:
+    state = engine.probe()
+    if state == "aether":
+        pid = engine.running_pid()
+        print(f"Engine: running on {config.HOST}:{config.PORT}" + (f" (pid {pid})" if pid else ""))
+    elif state == "other":
+        print(f"Engine: not running. {engine.port_taken_message()}")
+        return 1
+    else:
+        print("Engine: not running (it starts automatically when your AI tool needs it, or run `aether-cache start`)")
+    print(f"Data:   {config.DATA_DIR}")
+    if state == "aether":
+        from .server import project_name, run
+        project = project_name()
+        counts = Counter(status for _, status, _, _ in run("MEM.LIST", project, "STATUS", "any"))
+        summary = ", ".join(f"{counts[s]} {s}" for s in ("active", "stale", "superseded") if counts[s])
+        print(f"This project ({project}): {summary or 'no memories yet'}")
+    connected = [t for t in connect.TOOLS if connect.CHECKS[t]()]
+    print("Connected tools: " + (", ".join(connected) if connected else "none (run `aether-cache connect`)"))
+    return 0
+
+
+def cmd_connect(args) -> int:
+    if args.print:
+        print(connect.generic_instructions())
+        return 0
+    tools = args.tools or connect.detected()
+    if not tools:
+        print("No supported AI coding tools found (Claude Code, Cursor, Codex).\n")
+        print(connect.generic_instructions())
+        return 1
+    failed = False
+    for tool in tools:
+        done, message = connect.CONNECTORS[tool]()
+        _say(OK if done else FAIL, message)
+        failed |= not done
+    return 1 if failed else 0
+
+
+def cmd_doctor(args) -> int:
+    problems = 0
+    _say(OK, f"Aether Cache {__version__}, Python {sys.version.split()[0]} ({sys.executable})")
+    try:
+        java, major = engine.find_java()
+        _say(OK, f"Java {major} ({java})")
+    except engine.EngineError as e:
+        _say(FAIL, str(e))
+        problems += 1
+    if engine.JAR.is_file():
+        _say(OK, f"Engine file present ({engine.JAR.name})")
+    else:
+        _say(FAIL, f"Engine file missing ({engine.JAR}). Reinstall Aether Cache.")
+        problems += 1
+    state = engine.probe()
+    if state == "aether":
+        _say(OK, f"Engine answering on {config.HOST}:{config.PORT}")
+    elif state == "other":
+        _say(FAIL, engine.port_taken_message())
+        problems += 1
+    else:
+        _say(WARN, f"Engine not running. It starts automatically when needed; `aether-cache start` starts it now.\n"
+                   f"If it won't start, see {config.LOG_FILE}")
+    if config.FAKE_EMBEDDER:
+        _say(WARN, "Test embedder is on (AETHER_EMBEDDER=fake): search quality is poor. Unset it for real use.")
+    elif any(config.MODELS_DIR.glob("*")):
+        _say(OK, f"Embedding model downloaded ({config.MODELS_DIR})")
+    else:
+        _say(WARN, "Embedding model not downloaded yet; it downloads on first use (about 90 MB).")
+    for tool in connect.TOOLS:
+        if connect.CHECKS[tool]():
+            _say(OK, f"Connected to {tool}")
+        elif tool in connect.detected():
+            _say(WARN, f"{tool} is installed but not connected. Run `aether-cache connect {tool}`.")
+    from .server import git_toplevel, project_name
+    top = git_toplevel()
+    _say(OK if top else WARN, f"This folder's project: {project_name()}"
+         + ("" if top else " (not a git repo, so memories can't be linked to file versions here)"))
+    print("\nEverything looks good." if problems == 0 else f"\n{problems} problem(s) to fix above.")
+    return 1 if problems else 0
+
+
+def cmd_list(args) -> int:
+    from .server import EngineDown, project_name, run, store_down
+    try:
+        rows = run("MEM.LIST", project_name(), "STATUS", args.status)
+    except EngineDown as e:
+        print(store_down(e))
+        return 1
+    if not rows:
+        print(f"No {'' if args.status == 'any' else args.status + ' '}memories in {project_name()} yet.")
+    for mid, status, files, text in rows:
+        linked = ", ".join(f.rsplit("@", 1)[0] for f in files.split(",") if f)
+        print(f"{mid:>5}  {status:<10}  {text}" + (f"   [{linked}]" if linked else ""))
+    return 0
+
+
+def _tool_output(name: str, *tool_args) -> int:
+    from . import server
+    print(getattr(server, name)(*tool_args))
+    return 0
+
+
+def cmd_serve(args) -> int:
+    from .server import serve
+    serve()
+    return 0
+
+
+def main(argv=None) -> None:
+    try:
+        sys.stdout.reconfigure(errors="replace")  # never crash printing on a limited console
+    except (AttributeError, ValueError):
+        pass
+    parser = argparse.ArgumentParser(
+        prog="aether-cache",
+        description="Shared memory for AI coding tools that stays true to your code.")
+    parser.add_argument("--version", action="version", version=f"aether-cache {__version__}")
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+
+    p = sub.add_parser("setup", help="one-time setup: start the engine, download the model, connect your AI tools")
+    p.add_argument("tools", nargs="*", metavar="tool",
+                   help="which tools to connect (default: every supported tool found)")
+    p.set_defaults(func=cmd_setup)
+    p = sub.add_parser("connect", help="connect AI tools: claude-code, cursor, codex")
+    p.add_argument("tools", nargs="*", metavar="tool",
+                   help="which tools to connect (default: every supported tool found)")
+    p.add_argument("--print", action="store_true", help="print config for any other MCP tool instead")
+    p.set_defaults(func=cmd_connect)
+    sub.add_parser("start", help="start the engine in the background").set_defaults(func=cmd_start)
+    sub.add_parser("stop", help="stop the engine").set_defaults(func=cmd_stop)
+    sub.add_parser("status", help="is it running, and what's in this project's memory").set_defaults(func=cmd_status)
+    sub.add_parser("doctor", help="check everything and say how to fix problems").set_defaults(func=cmd_doctor)
+    p = sub.add_parser("list", help="list this project's memories")
+    p.add_argument("--status", default="active", choices=["active", "stale", "superseded", "any"])
+    p.set_defaults(func=cmd_list)
+    sub.add_parser("recall", help="search this project's memories").add_argument("query")
+    sub.choices["recall"].set_defaults(func=lambda a: _tool_output("recall", a.query))
+    sub.add_parser("explain", help="where a memory came from and its history").add_argument("id")
+    sub.choices["explain"].set_defaults(func=lambda a: _tool_output("explain_memory", a.id))
+    sub.add_parser("sync", help="write current memories into AGENTS.md / CLAUDE.md").set_defaults(
+        func=lambda a: _tool_output("sync_to_files"))
+    sub.add_parser("check", help="retire memories whose linked files changed").set_defaults(
+        func=lambda a: _tool_output("check_stale"))
+    sub.add_parser("serve", help="run the MCP server (your AI tool runs this for you)").set_defaults(func=cmd_serve)
+
+    args = parser.parse_args(argv)
+    unknown = [t for t in getattr(args, "tools", None) or [] if t not in connect.TOOLS]
+    if unknown:
+        parser.error(f"unknown tool {unknown[0]!r}; choose from {', '.join(connect.TOOLS)} "
+                     f"(or `aether-cache connect --print` for any other MCP tool)")
+    if not getattr(args, "func", None):
+        parser.print_help()
+        print("\nNew here? Run `aether-cache setup`.")
+        sys.exit(0)
+    try:
+        sys.exit(args.func(args))
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except BrokenPipeError:  # output piped into something like `head` that stopped reading
+        sys.stderr.close()
+        sys.exit(0)

aether_cache/config.py

@@ -0,0 +1,44 @@
+"""Where Aether Cache keeps things, and how to reach the engine. All settings are optional."""
+import os
+from pathlib import Path
+
+
+def _env(*names: str, default: str = "") -> str:
+    """First set environment variable among names (newer AETHER_* names win over older MEMORY_* ones)."""
+    for name in names:
+        value = os.environ.get(name)
+        if value:
+            return value
+    return default
+
+
+# Everything lives under one folder: the engine's data, its log, and the downloaded embedding model.
+HOME = Path(_env("AETHER_HOME", default=str(Path.home() / ".aether-cache"))).expanduser()
+DATA_DIR = HOME / "data"
+LOG_FILE = HOME / "engine.log"
+PID_FILE = HOME / "engine.pid"
+MODELS_DIR = HOME / "models"
+
+# The engine listens on this machine only. The port is deliberately not Redis's 6379, so Aether Cache
+# never collides with a real Redis you may already run.
+HOST = _env("AETHER_HOST", "MEMORY_HOST", default="127.0.0.1")
+PORT = int(_env("AETHER_PORT", "MEMORY_PORT", default="7380"))
+
+# Which AI tool this server is running for (recorded with every memory it saves).
+SOURCE = _env("AETHER_SOURCE", "MEMORY_SOURCE", default="unknown")
+MODEL = _env("AETHER_MODEL", "MEMORY_MODEL", default="sentence-transformers/all-MiniLM-L6-v2")
+FAKE_EMBEDDER = _env("AETHER_EMBEDDER", "MEMORY_EMBEDDER") == "fake"  # testing only, needs no download
+# Existing memories at least this similar to a newly saved one are shown to the AI to judge.
+# Low on purpose: in calibration, "we use Postgres" vs "we migrated to MySQL" scored only 0.30.
+RELATED_SIMILARITY = float(_env("AETHER_RELATED_SIMILARITY", "MEMORY_RELATED_SIMILARITY", default="0.25"))
+
+
+def project_override() -> str:
+    return _env("AETHER_PROJECT", "MEMORY_PROJECT")
+
+
+def repo_override() -> str:
+    """The project folder, when the AI tool says where it is (Cursor passes ${workspaceFolder}).
+    Ignored if the tool didn't fill in the placeholder."""
+    value = _env("AETHER_REPO", "MEMORY_REPO")
+    return "" if "${" in value else value

aether_cache/connect.py

@@ -0,0 +1,195 @@
+"""Registering Aether Cache with AI coding tools, so they start its MCP server on their own."""
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import List, Tuple
+
+NAME = "aether-cache"
+TOOLS = ["claude-code", "cursor", "codex"]
+
+
+def settings_env() -> dict:
+    """Non-default settings from this shell (a custom port or data folder) that the tools must use too."""
+    return {k: os.environ[k] for k in ("AETHER_PORT", "AETHER_HOME") if os.environ.get(k)}
+
+
+def server_command() -> List[str]:
+    """How a tool launches the server: this exact Python, so it works even when the tool's PATH
+    doesn't include the folder the `aether-cache` command was installed into."""
+    return [sys.executable, "-m", "aether_cache", "serve"]
+
+
+def cursor_config() -> Path:
+    return Path.home() / ".cursor" / "mcp.json"
+
+
+def codex_config() -> Path:
+    return Path(os.environ.get("CODEX_HOME", Path.home() / ".codex")) / "config.toml"
+
+
+def detected() -> List[str]:
+    """The supported tools that look installed on this machine."""
+    found = []
+    if shutil.which("claude"):
+        found.append("claude-code")
+    if (Path.home() / ".cursor").is_dir():
+        found.append("cursor")
+    if shutil.which("codex") or codex_config().parent.is_dir():
+        found.append("codex")
+    return found
+
+
+# ---------- instruction files ----------
+
+INSTR_START = "<!-- aether-cache:instructions:start -->"
+INSTR_END = "<!-- aether-cache:instructions:end -->"
+
+
+def add_instructions(path: Path) -> str:
+    """Adds (or refreshes) a short, clearly marked section telling the AI to use Aether Cache for project
+    memory. Without it, tools tend to reach for their built-in memory instead. Nothing else is touched."""
+    from .server import INSTRUCTIONS
+    block = f"{INSTR_START}\n## Project memory\n{INSTRUCTIONS}\n{INSTR_END}"
+    old = path.read_text(encoding="utf-8") if path.exists() else ""
+    if INSTR_START in old and INSTR_END in old:
+        new = old[:old.index(INSTR_START)] + block + old[old.index(INSTR_END) + len(INSTR_END):]
+    else:
+        new = (old.rstrip() + "\n\n" if old.strip() else "") + block + "\n"
+    if new != old:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_name(path.name + ".aether-tmp")
+        tmp.write_text(new, encoding="utf-8")
+        os.replace(tmp, path)
+    return f"told it to use Aether Cache for project memory in {path}"
+
+
+def claude_instructions_file() -> Path:
+    return Path(os.environ.get("CLAUDE_CONFIG_DIR", Path.home() / ".claude")) / "CLAUDE.md"
+
+
+# ---------- Claude Code ----------
+
+def _claude(*args: str) -> subprocess.CompletedProcess:
+    return subprocess.run([shutil.which("claude") or "claude", *args], capture_output=True, text=True, timeout=60)
+
+
+def connect_claude_code() -> Tuple[bool, str]:
+    if not shutil.which("claude"):
+        return False, "Claude Code isn't installed (no `claude` command found)."
+    notes = []
+    # replace any earlier registration, including the one from when the project was called memstore
+    for old in (NAME, "memstore"):
+        if _claude("mcp", "get", old).returncode == 0:
+            for scope in ("user", "local"):
+                if _claude("mcp", "remove", old, "--scope", scope).returncode == 0 and old == "memstore":
+                    notes.append("removed the old `memstore` entry")
+    cmd = server_command()
+    env_flags = [x for k, v in settings_env().items() for x in ("-e", f"{k}={v}")]
+    out = _claude("mcp", "add", NAME, "--scope", "user", "-e", "MEMORY_SOURCE=claude-code", *env_flags, "--", *cmd)
+    if out.returncode != 0:
+        return False, f"`claude mcp add` failed: {(out.stderr or out.stdout).strip()}"
+    notes.append(add_instructions(claude_instructions_file()))
+    return True, "Claude Code: connected for all projects (" + "; ".join(notes) + ")."
+
+
+def claude_code_connected() -> bool:
+    return bool(shutil.which("claude")) and _claude("mcp", "get", NAME).returncode == 0
+
+
+# ---------- Cursor ----------
+
+def _server_entry(source: str, workspace_var: str = "") -> dict:
+    cmd = server_command()
+    env = {"MEMORY_SOURCE": source, **settings_env()}
+    if workspace_var:
+        env["AETHER_REPO"] = workspace_var  # tells the server which project folder is open
+    return {"command": cmd[0], "args": cmd[1:], "env": env}
+
+
+def connect_cursor() -> Tuple[bool, str]:
+    path = cursor_config()
+    data = {}
+    if path.exists():
+        text = path.read_text(encoding="utf-8")
+        try:
+            data = json.loads(text) if text.strip() else {}
+        except json.JSONDecodeError as e:
+            return False, (f"Couldn't read {path} ({e}). Fix it, or add this under \"mcpServers\" yourself:\n"
+                           + json.dumps({NAME: _server_entry("cursor", "${workspaceFolder}")}, indent=2))
+        shutil.copyfile(path, path.with_name("mcp.json.bak"))
+    data.setdefault("mcpServers", {})[NAME] = _server_entry("cursor", "${workspaceFolder}")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name("mcp.json.aether-tmp")
+    tmp.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    os.replace(tmp, path)
+    return True, f"Cursor: connected for all projects ({path}). Restart Cursor to pick it up."
+
+
+def cursor_connected() -> bool:
+    try:
+        return NAME in json.loads(cursor_config().read_text(encoding="utf-8")).get("mcpServers", {})
+    except (OSError, ValueError, AttributeError):
+        return False
+
+
+# ---------- Codex ----------
+
+def _codex_block() -> str:
+    cmd = server_command()
+    q = json.dumps  # TOML basic strings use the same escaping as JSON strings
+    return (f"[mcp_servers.{NAME}]\n"
+            f"command = {q(cmd[0])}\n"
+            f"args = [{', '.join(q(a) for a in cmd[1:])}]\n"
+            "env = { " + ", ".join(f"{k} = {q(v)}" for k, v in {"MEMORY_SOURCE": "codex", **settings_env()}.items())
+            + " }\n")
+
+
+def _is_our_header(line: str) -> bool:
+    s = line.strip().replace('"', "").replace("'", "")
+    return s == f"[mcp_servers.{NAME}]" or s.startswith(f"[mcp_servers.{NAME}.")
+
+
+def connect_codex() -> Tuple[bool, str]:
+    path = codex_config()
+    text = path.read_text(encoding="utf-8") if path.exists() else ""
+    # drop our old section (if any): from its header to the next table header
+    kept, skipping = [], False
+    for line in text.splitlines():
+        if line.strip().startswith("["):
+            skipping = _is_our_header(line)
+        if not skipping:
+            kept.append(line)
+    body = "\n".join(kept).rstrip()
+    new = (body + "\n\n" if body else "") + _codex_block()
+    if path.exists():
+        shutil.copyfile(path, path.with_name("config.toml.bak"))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name("config.toml.aether-tmp")
+    tmp.write_text(new, encoding="utf-8")
+    os.replace(tmp, path)
+    note = add_instructions(path.with_name("AGENTS.md"))  # Codex's instructions for every project
+    return True, f"Codex: connected ({path}; {note})."
+
+
+def codex_connected() -> bool:
+    try:
+        return any(_is_our_header(l) for l in codex_config().read_text(encoding="utf-8").splitlines())
+    except OSError:
+        return False
+
+
+# ---------- any other MCP tool ----------
+
+def generic_instructions() -> str:
+    entry = _server_entry("your-tool-name")
+    return ("For any other MCP-capable tool, add this server to its MCP config (most use this JSON shape):\n\n"
+            + json.dumps({"mcpServers": {NAME: entry}}, indent=2)
+            + "\n\nOr, as a single command: " + " ".join(f'"{c}"' if " " in c else c for c in server_command())
+            + "\nRun the tool from your project folder, or set AETHER_REPO to the project's path.")
+
+
+CONNECTORS = {"claude-code": connect_claude_code, "cursor": connect_cursor, "codex": connect_codex}
+CHECKS = {"claude-code": claude_code_connected, "cursor": cursor_connected, "codex": codex_connected}