hindsight-zed 0.1.0__tar.gz

hindsight_zed-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+.venv/
+__pycache__/
+*.pyc

hindsight_zed-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: hindsight-zed
+Version: 0.1.0
+Summary: Automatic long-term memory for the Zed editor's AI assistant via Hindsight
+Project-URL: Homepage, https://github.com/vectorize-io/hindsight
+Project-URL: Documentation, https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/zed
+Project-URL: Repository, https://github.com/vectorize-io/hindsight
+Author-email: Vectorize <support@vectorize.io>
+License: MIT
+Keywords: agents,ai,coding,hindsight,memory,zed
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# hindsight-zed
+
+Long-term memory for the [Zed](https://zed.dev) editor's AI assistant, powered by
+[Hindsight](https://github.com/vectorize-io/hindsight).
+
+`hindsight-zed init` wires Zed's Agent Panel to the Hindsight **MCP server** and
+adds a rule telling the agent to use it — so it recalls relevant memory at the
+start of a task and retains durable facts as it goes. Recall happens at query
+time against your actual message (no lag), and from your seat it's automatic.
+
+## How it works
+
+Zed has no pre-prompt hook, but it does support two things this integration uses:
+
+- **MCP context servers** — Zed runs MCP servers configured under
+  `context_servers` in `settings.json` and exposes their tools in the Agent
+  Panel. We register the Hindsight MCP server there, giving the agent
+  `recall` / `retain` / `reflect` tools.
+- **A global instructions file** (`~/.config/zed/AGENTS.md`) that Zed includes in
+  every conversation. We add a small rule there telling the agent to recall
+  first and retain what it learns.
+
+Zed doesn't yet have native HTTP-MCP transport, so the server is connected
+through the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) stdio bridge
+(run via `npx`) — that means you need Node.js installed.
+
+## Install
+
+```bash
+pip install hindsight-zed
+hindsight-zed init --api-token YOUR_HINDSIGHT_API_KEY --bank-id my-memory
+```
+
+`init` adds the `hindsight` MCP server to `~/.config/zed/settings.json` and the
+recall/retain rule to `~/.config/zed/AGENTS.md`. Restart Zed, open the Agent
+Panel, and the `hindsight` server should show a green dot.
+
+Use a [Hindsight Cloud](https://hindsight.vectorize.io) key, or point at a
+self-hosted server with `--api-url http://localhost:8888` (no token needed for an
+open local server).
+
+> If your `settings.json` contains comments (JSONC), `init` won't rewrite it —
+> it prints the exact `context_servers` entry for you to paste instead. Use
+> `hindsight-zed init --print-only` any time to see the snippet without writing.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `hindsight-zed init` | Add the MCP server + recall/retain rule |
+| `hindsight-zed status` | Show whether the server + rule are configured |
+| `hindsight-zed uninstall` | Remove the server + rule |
+| `hindsight-zed init --print-only` | Print the config to add manually |
+
+## What gets written
+
+`~/.config/zed/settings.json`:
+
+```jsonc
+{
+  "context_servers": {
+    "hindsight": {
+      "source": "custom",
+      "command": "npx",
+      "args": [
+        "-y", "mcp-remote",
+        "https://api.hindsight.vectorize.io/mcp/my-memory/",
+        "--header", "Authorization: Bearer YOUR_HINDSIGHT_API_KEY"
+      ]
+    }
+  }
+}
+```
+
+`~/.config/zed/AGENTS.md` (inside a fenced `<!-- HINDSIGHT -->` block that leaves
+the rest of the file untouched): a short rule telling the agent to `recall` at
+the start of each task and `retain` durable facts.
+
+## Configuration
+
+| Setting | Env var | Default |
+| --- | --- | --- |
+| API URL | `HINDSIGHT_API_URL` | `https://api.hindsight.vectorize.io` |
+| API token | `HINDSIGHT_API_TOKEN` | _(none; required for Cloud)_ |
+| Bank id | `HINDSIGHT_ZED_BANK_ID` | `zed` |
+
+These can also live in `~/.hindsight/zed.json` (written by `init`).
+
+## Development
+
+```bash
+uv sync
+uv run pytest tests -v -m 'not requires_real_llm'   # deterministic suite
+uv run pytest tests -v -m requires_real_llm          # gated MCP-endpoint check
+```
+
+## License
+
+MIT

hindsight_zed-0.1.0/README.md

@@ -0,0 +1,99 @@
+# hindsight-zed
+
+Long-term memory for the [Zed](https://zed.dev) editor's AI assistant, powered by
+[Hindsight](https://github.com/vectorize-io/hindsight).
+
+`hindsight-zed init` wires Zed's Agent Panel to the Hindsight **MCP server** and
+adds a rule telling the agent to use it — so it recalls relevant memory at the
+start of a task and retains durable facts as it goes. Recall happens at query
+time against your actual message (no lag), and from your seat it's automatic.
+
+## How it works
+
+Zed has no pre-prompt hook, but it does support two things this integration uses:
+
+- **MCP context servers** — Zed runs MCP servers configured under
+  `context_servers` in `settings.json` and exposes their tools in the Agent
+  Panel. We register the Hindsight MCP server there, giving the agent
+  `recall` / `retain` / `reflect` tools.
+- **A global instructions file** (`~/.config/zed/AGENTS.md`) that Zed includes in
+  every conversation. We add a small rule there telling the agent to recall
+  first and retain what it learns.
+
+Zed doesn't yet have native HTTP-MCP transport, so the server is connected
+through the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) stdio bridge
+(run via `npx`) — that means you need Node.js installed.
+
+## Install
+
+```bash
+pip install hindsight-zed
+hindsight-zed init --api-token YOUR_HINDSIGHT_API_KEY --bank-id my-memory
+```
+
+`init` adds the `hindsight` MCP server to `~/.config/zed/settings.json` and the
+recall/retain rule to `~/.config/zed/AGENTS.md`. Restart Zed, open the Agent
+Panel, and the `hindsight` server should show a green dot.
+
+Use a [Hindsight Cloud](https://hindsight.vectorize.io) key, or point at a
+self-hosted server with `--api-url http://localhost:8888` (no token needed for an
+open local server).
+
+> If your `settings.json` contains comments (JSONC), `init` won't rewrite it —
+> it prints the exact `context_servers` entry for you to paste instead. Use
+> `hindsight-zed init --print-only` any time to see the snippet without writing.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `hindsight-zed init` | Add the MCP server + recall/retain rule |
+| `hindsight-zed status` | Show whether the server + rule are configured |
+| `hindsight-zed uninstall` | Remove the server + rule |
+| `hindsight-zed init --print-only` | Print the config to add manually |
+
+## What gets written
+
+`~/.config/zed/settings.json`:
+
+```jsonc
+{
+  "context_servers": {
+    "hindsight": {
+      "source": "custom",
+      "command": "npx",
+      "args": [
+        "-y", "mcp-remote",
+        "https://api.hindsight.vectorize.io/mcp/my-memory/",
+        "--header", "Authorization: Bearer YOUR_HINDSIGHT_API_KEY"
+      ]
+    }
+  }
+}
+```
+
+`~/.config/zed/AGENTS.md` (inside a fenced `<!-- HINDSIGHT -->` block that leaves
+the rest of the file untouched): a short rule telling the agent to `recall` at
+the start of each task and `retain` durable facts.
+
+## Configuration
+
+| Setting | Env var | Default |
+| --- | --- | --- |
+| API URL | `HINDSIGHT_API_URL` | `https://api.hindsight.vectorize.io` |
+| API token | `HINDSIGHT_API_TOKEN` | _(none; required for Cloud)_ |
+| Bank id | `HINDSIGHT_ZED_BANK_ID` | `zed` |
+
+These can also live in `~/.hindsight/zed.json` (written by `init`).
+
+## Development
+
+```bash
+uv sync
+uv run pytest tests -v -m 'not requires_real_llm'   # deterministic suite
+uv run pytest tests -v -m requires_real_llm          # gated MCP-endpoint check
+```
+
+## License
+
+MIT

hindsight_zed-0.1.0/hindsight_zed/__init__.py

@@ -0,0 +1,3 @@
+"""Hindsight memory integration for the Zed editor."""
+
+__version__ = "0.1.0"

hindsight_zed-0.1.0/hindsight_zed/cli.py

@@ -0,0 +1,173 @@
+"""CLI for the Hindsight Zed integration.
+
+``hindsight-zed init`` wires Zed's MCP ``context_servers`` to the Hindsight MCP
+endpoint and writes a recall/retain rule into Zed's global instructions file.
+After that, Zed's Agent Panel has ``recall``/``retain``/``reflect`` tools and is
+told (via the rule) to use them automatically. There is no background process.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from . import __version__
+from .config import USER_CONFIG_FILE, ZedConfig, load_config
+from .rules_file import RULE_TEXT, clear_rule, default_rules_path, write_rule
+from .rules_file import is_installed as rule_installed
+from .zed_settings import (
+    SettingsResult,
+    apply_to_settings,
+    build_context_server,
+    default_settings_path,
+    remove_from_settings,
+    render_snippet,
+)
+from .zed_settings import (
+    is_installed as server_installed,
+)
+
+
+@dataclass
+class InstallOutcome:
+    """Result of an ``init``: how the settings file changed and where the rule went."""
+
+    settings: SettingsResult
+    rules_path: Path
+
+
+def build_install(config: ZedConfig, settings_path: Path, rules_path: Path) -> InstallOutcome:
+    """Apply the MCP server entry and the recall/retain rule (the testable core)."""
+    server = build_context_server(config.hindsight_api_url, config.hindsight_api_token, config.bank_id)
+    settings = apply_to_settings(settings_path, server)
+    write_rule(rules_path)
+    return InstallOutcome(settings=settings, rules_path=rules_path)
+
+
+def _config_path(args: argparse.Namespace) -> Path:
+    return Path(args.config_path) if args.config_path else USER_CONFIG_FILE
+
+
+def _resolve_config(args: argparse.Namespace) -> ZedConfig:
+    """Config from file/env, overridden by any explicitly-passed CLI flags."""
+    cfg = load_config(config_file=_config_path(args))
+    if args.api_url:
+        cfg.hindsight_api_url = args.api_url
+    if args.api_token:
+        cfg.hindsight_api_token = args.api_token
+    if args.bank_id:
+        cfg.bank_id = args.bank_id
+    return cfg
+
+
+def _scaffold_config(cfg: ZedConfig, config_path: Path) -> None:
+    """Persist the resolved connection settings so re-runs remember them."""
+    if config_path.is_file():
+        return
+    data = {"hindsightApiUrl": cfg.hindsight_api_url, "bankId": cfg.bank_id}
+    if cfg.hindsight_api_token:
+        data["hindsightApiToken"] = cfg.hindsight_api_token
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def cmd_init(args: argparse.Namespace) -> None:
+    cfg = _resolve_config(args)
+    settings_path = Path(args.settings_path) if args.settings_path else default_settings_path()
+    rules_path = Path(args.rules_path) if args.rules_path else default_rules_path()
+    server = build_context_server(cfg.hindsight_api_url, cfg.hindsight_api_token, cfg.bank_id)
+
+    if args.print_only:
+        print("Add this to your Zed settings.json:\n")
+        print(render_snippet(server))
+        print("\nAnd add this rule to ~/.config/zed/AGENTS.md:\n")
+        print(RULE_TEXT)
+        return
+
+    print("Setting up Hindsight for Zed ...")
+    _scaffold_config(cfg, _config_path(args))
+    outcome = build_install(cfg, settings_path, rules_path)
+
+    if outcome.settings.action == "manual":
+        print(f"  Your {outcome.settings.path} has comments, so I won't rewrite it.")
+        print("  Add this `context_servers` entry yourself:\n")
+        print(render_snippet(server))
+    else:
+        verb = {"created": "Created", "merged": "Updated", "unchanged": "Already configured in"}[
+            outcome.settings.action
+        ]
+        print(f"  {verb} {outcome.settings.path} (MCP server: hindsight → bank '{cfg.bank_id}')")
+    print(f"  Wrote recall/retain rule to {outcome.rules_path}")
+
+    if shutil.which("npx") is None:
+        print("\n  warning: `npx` (Node.js) was not found on PATH. Zed runs the MCP")
+        print("  bridge via `npx mcp-remote`, so install Node.js for the server to start.")
+
+    print("\nDone. Restart Zed, open the Agent Panel, and the `hindsight` MCP server")
+    print("should show a green dot. Memory recall/retain then happen automatically.")
+
+
+def cmd_status(args: argparse.Namespace) -> None:
+    settings_path = Path(args.settings_path) if args.settings_path else default_settings_path()
+    rules_path = Path(args.rules_path) if args.rules_path else default_rules_path()
+    print(f"MCP server in {settings_path}: {'installed' if server_installed(settings_path) else 'not installed'}")
+    print(f"Recall/retain rule in {rules_path}: {'installed' if rule_installed(rules_path) else 'not installed'}")
+
+
+def cmd_uninstall(args: argparse.Namespace) -> None:
+    settings_path = Path(args.settings_path) if args.settings_path else default_settings_path()
+    rules_path = Path(args.rules_path) if args.rules_path else default_rules_path()
+    result = remove_from_settings(settings_path)
+    if result.action == "manual":
+        print(f"  {settings_path} has comments — remove the `hindsight` context_servers entry yourself.")
+    elif result.action == "removed":
+        print(f"  Removed the hindsight MCP server from {settings_path}")
+    else:
+        print(f"  No hindsight MCP server found in {settings_path}")
+    clear_rule(rules_path)
+    print(f"  Removed the recall/retain rule from {rules_path}")
+
+
+def _add_path_overrides(parser: argparse.ArgumentParser) -> None:
+    # Hidden overrides used by tests and advanced setups.
+    parser.add_argument("--settings-path", default=None, help=argparse.SUPPRESS)
+    parser.add_argument("--rules-path", default=None, help=argparse.SUPPRESS)
+    parser.add_argument("--config-path", default=None, help=argparse.SUPPRESS)
+
+
+def main(argv: Optional[list] = None) -> int:
+    parser = argparse.ArgumentParser(prog="hindsight-zed", description="Hindsight memory for Zed (via MCP)")
+    parser.add_argument("--version", action="version", version=f"hindsight-zed {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    init_p = sub.add_parser("init", help="Configure Zed's MCP server + recall/retain rule")
+    init_p.add_argument("--api-url", default=None, help="Hindsight API URL (default: cloud)")
+    init_p.add_argument("--api-token", default=None, help="Hindsight API token (for Cloud)")
+    init_p.add_argument("--bank-id", default=None, help="Memory bank for the MCP server (default: zed)")
+    init_p.add_argument("--print-only", action="store_true", help="Print the config to add manually; write nothing")
+    _add_path_overrides(init_p)
+    init_p.set_defaults(func=cmd_init)
+
+    status_p = sub.add_parser("status", help="Show whether the MCP server + rule are configured")
+    _add_path_overrides(status_p)
+    status_p.set_defaults(func=cmd_status)
+
+    uninst_p = sub.add_parser("uninstall", help="Remove the MCP server + rule")
+    _add_path_overrides(uninst_p)
+    uninst_p.set_defaults(func=cmd_uninstall)
+
+    args = parser.parse_args(argv)
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return 1
+    args.func(args)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hindsight_zed-0.1.0/hindsight_zed/config.py

@@ -0,0 +1,79 @@
+"""Configuration for the Hindsight Zed integration.
+
+Settings layer (later wins): built-in defaults → ``~/.hindsight/zed.json`` →
+environment variables. Resolved into a typed :class:`ZedConfig`.
+
+The integration is configuration-only: it wires Zed's MCP ``context_servers`` to
+the Hindsight MCP endpoint and writes a recall/retain rule into Zed's global
+instructions file. Memory operations happen through the MCP server at runtime,
+so there is no daemon or direct API client here.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+# Cross-integration cloud-default convention.
+DEFAULT_HINDSIGHT_API_URL = "https://api.hindsight.vectorize.io"
+DEFAULT_BANK_ID = "zed"
+
+USER_CONFIG_FILE = Path.home() / ".hindsight" / "zed.json"
+
+
+@dataclass
+class ZedConfig:
+    """Resolved configuration for the Zed MCP setup."""
+
+    hindsight_api_url: str = DEFAULT_HINDSIGHT_API_URL
+    hindsight_api_token: Optional[str] = None
+    # The memory bank the Zed MCP server is scoped to (it's the last path
+    # segment of the MCP endpoint URL).
+    bank_id: str = DEFAULT_BANK_ID
+
+
+# user-config file key -> attribute
+_FILE_KEYS = {
+    "hindsightApiUrl": "hindsight_api_url",
+    "hindsightApiToken": "hindsight_api_token",
+    "bankId": "bank_id",
+}
+
+# env var -> attribute
+_ENV_KEYS = {
+    "HINDSIGHT_API_URL": "hindsight_api_url",
+    "HINDSIGHT_API_TOKEN": "hindsight_api_token",
+    "HINDSIGHT_ZED_BANK_ID": "bank_id",
+}
+
+
+def load_config(config_file: Optional[Path] = None, env: Optional[dict] = None) -> ZedConfig:
+    """Load and resolve configuration from file then environment."""
+    cfg = ZedConfig()
+    env = os.environ if env is None else env
+
+    path = config_file if config_file is not None else USER_CONFIG_FILE
+    if path.is_file():
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            data = {}
+        for key, attr in _FILE_KEYS.items():
+            value = data.get(key)
+            if value:
+                setattr(cfg, attr, str(value))
+
+    for key, attr in _ENV_KEYS.items():
+        value = env.get(key)
+        if value:
+            setattr(cfg, attr, str(value))
+
+    if not cfg.hindsight_api_url:
+        cfg.hindsight_api_url = DEFAULT_HINDSIGHT_API_URL
+    if not cfg.bank_id:
+        cfg.bank_id = DEFAULT_BANK_ID
+
+    return cfg

hindsight_zed-0.1.0/hindsight_zed/rules_file.py

@@ -0,0 +1,97 @@
+"""Manage Hindsight's recall/retain rule inside Zed's global instructions file.
+
+Zed includes a global instructions file (``~/.config/zed/AGENTS.md`` on macOS and
+Linux) in **every** agent conversation. We write a static rule there telling the
+agent to use the Hindsight MCP tools — recall relevant memory at the start of a
+task, and retain durable facts as it learns them.
+
+The rule lives inside a fenced ``<!-- HINDSIGHT:BEGIN -->`` … ``<!-- HINDSIGHT:END -->``
+block so we can update or remove it without touching the user's own rules in the
+same file.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+BEGIN_MARKER = "<!-- HINDSIGHT:BEGIN -->"
+END_MARKER = "<!-- HINDSIGHT:END -->"
+
+# The recall/retain instruction injected into Zed's global rules.
+RULE_TEXT = (
+    "You have persistent long-term memory through the Hindsight MCP server "
+    "(`recall`, `retain`, and `reflect` tools).\n\n"
+    "- At the start of each task, call `recall` with the user's request to load "
+    "relevant decisions, preferences, and project context before you answer. "
+    "Use what's relevant and ignore the rest.\n"
+    "- When you learn a durable fact — an architectural decision, a user "
+    "preference, a convention, or anything worth remembering across sessions — "
+    "call `retain` to store it.\n"
+    "- Do not mention these memory operations unless the user asks about them."
+)
+
+
+def default_rules_path() -> Path:
+    """Zed's global instructions file (``~/.config/zed/AGENTS.md``)."""
+    return Path.home() / ".config" / "zed" / "AGENTS.md"
+
+
+def _strip_block(text: str) -> str:
+    """Remove an existing HINDSIGHT block (and its surrounding blank lines)."""
+    start = text.find(BEGIN_MARKER)
+    if start == -1:
+        return text
+    end = text.find(END_MARKER, start)
+    if end == -1:
+        # Malformed (begin without end) — drop from the marker onward.
+        return text[:start].rstrip() + "\n"
+    end += len(END_MARKER)
+    before = text[:start].rstrip()
+    after = text[end:].lstrip()
+    if before and after:
+        return f"{before}\n\n{after}"
+    return (before or after).rstrip() + ("\n" if (before or after) else "")
+
+
+def render_block(rule_text: str = RULE_TEXT) -> str:
+    """Render the fenced HINDSIGHT rule block (no trailing newline)."""
+    return f"{BEGIN_MARKER}\n{rule_text.strip()}\n{END_MARKER}"
+
+
+def write_rule(path: Path, rule_text: str = RULE_TEXT) -> Path:
+    """Write/replace Hindsight's rule block in the instructions file at ``path``.
+
+    Preserves any user-authored content and only rewrites our fenced block,
+    placing it at the top so the memory rule leads the instructions.
+    """
+    existing = path.read_text(encoding="utf-8") if path.is_file() else ""
+    base = _strip_block(existing).rstrip()
+    block = render_block(rule_text)
+    new_text = f"{block}\n\n{base}\n" if base else f"{block}\n"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(new_text, encoding="utf-8")
+    return path
+
+
+def clear_rule(path: Path) -> Path:
+    """Remove Hindsight's rule block from the instructions file, if present.
+
+    Leaves the rest of the file intact. If removing the block empties a file that
+    held nothing else, the file is deleted.
+    """
+    if not path.is_file():
+        return path
+    existing = path.read_text(encoding="utf-8")
+    if BEGIN_MARKER not in existing:
+        return path
+    stripped = _strip_block(existing).strip()
+    if not stripped:
+        path.unlink()
+        return path
+    path.write_text(stripped + "\n", encoding="utf-8")
+    return path
+
+
+def is_installed(path: Path) -> bool:
+    """Whether our rule block is present in the instructions file at ``path``."""
+    return path.is_file() and BEGIN_MARKER in path.read_text(encoding="utf-8")