waystone 0.4.45

A context intelligence layer for LLM workflows

Waystone

Persistent cross-session memory for LLM agents. A knowledge graph that stores decisions, constraints, and context across coding sessions — so your agent starts informed, not blank.

Install

pip install waystone

Requires Python 3.11+. An LLM API key is needed for extraction (Gemini Flash recommended — fast and cheap).

Quick start

Option 1: MCP server (recommended)

Add to your editor's MCP config:

{
  "mcpServers": {
    "waystone": {
      "command": "waystone",
      "args": ["mcp-serve"],
      "env": { "WAYSTONE_PROJECT": "my-project" }
    }
  }
}

Restart your editor. waystone_query, waystone_extract, and waystone_stats appear as tools. Your agent pulls context when it needs it.

Option 2: Claude Code hooks (zero manual calls)

Run the installer — it wires the hooks into ~/.claude/settings.json for you:

waystone configure

Then mark a project directory so the hooks know which graph to use:

cd ~/code/my-project && waystone hook-init my-project

Context is injected automatically before every prompt (UserPromptSubmit), and facts are extracted automatically when Claude finishes (Stop). Verify any time with waystone doctor.

Manual setup (what configure writes)

The hooks are pip-installed console scripts that read Claude Code's hook JSON on stdin — add to ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "waystone-hook-submit" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "waystone-hook-stop" }] }]
  }
}

The project is auto-detected from the nearest .waystone marker (see hook-init).

Supported clients

Claude Code · Cursor · Windsurf · Continue.dev · Cline · Zed · OpenClaw · Hermes

Full per-client setup: unbidden.ai/docs/mcp-server/

Hermes Agent (native memory provider)

Beyond MCP, Waystone ships a first-class Hermes Agent memory provider (hermes_plugin/). It plugs the knowledge graph into Hermes as a Tier-3 memory backend:

• prefetch() injects relevant graph context before each LLM call (in-process — the embedding model loads once and stays warm, so per-turn retrieval stays sub-second).
• waystone_query / waystone_recall tools let the agent search the graph on demand.
• on_session_end extraction grows the graph in the background. Fully local — no data leaves the machine.

Install:

cp -r hermes_plugin/ /path/to/hermes-agent/plugins/memory/waystone/
pip install waystone
hermes memory setup        # pick "waystone", set the project

Key CLI commands

waystone init <project>              # create a project
waystone extract <project> <file>    # extract facts from a transcript
waystone query <project> "<query>"   # retrieve relevant context
waystone onboard <project>           # import existing session history
waystone show <project>              # view project stats
waystone story <project>             # replay the project's session-summary timeline
waystone catchup-summarize <project> # back-fill the story from saved transcripts
waystone doctor                      # health check (config, LLM, MCP, sqlite-vec)

How it works

At session end — waystone extract reads the conversation transcript and pulls structured facts: decisions, constraints, implementations, lessons learned, open questions. These are stored as nodes in a local SQLite knowledge graph (~/.waystone/). Superseded facts are retired automatically — if a decision changes, the graph reflects the current state.

At session start — waystone_query (or a hook) runs BFS traversal from the most relevant entry points and surfaces the top 10–25 facts. Only what's relevant to the current context, not everything ever stored.

Session summaries (the project's story) — alongside atomic facts, Waystone keeps a rolling, high-altitude narrative of each work session (goal · arc · current state · next) that point-facts miss. A passive background worker updates it every few turns; each summary supersedes the prior one, but the full timeline is kept. Every new prompt is led with a "Where we are" block so a fresh session opens already oriented, and waystone story <project> replays the whole history chapter by chapter. Use waystone catchup-summarize <project> once to back-fill the story from a project's existing transcripts. The rolling call is bounded (~3k tokens in / ≤512 out regardless of session length), so it stays cheap.

Benchmarks

Tested on 23 questions across 3 domains (API design, auth systems, data pipelines):

	Recall
Baseline	82%
With retrieval improvements	89%

Token usage vs. naive MEMORY.md on a mature project: typically 60–80% fewer context tokens per session (exact savings depend on project age and query specificity).

Full results: BENCHMARK_RESULTS.md

Team Server (self-hosted)

Run one shared graph for your whole team — on your own infrastructure. Each member's Claude Code session injects the team's context every prompt and writes new decisions back to the same graph, automatically. No data leaves your network.

cp .env.example .env        # set WAYSTONE_API_KEY + LLM_API_KEY
docker compose up -d        # Postgres (pgvector) + the API, ready in ~30s

Point each member's client at it (~/.waystone/config.yaml):

backend: remote
api_url: http://<server-host>:8000
api_key: <the shared key you set>

That's it — query / extract / show / export and the Claude Code hooks now all operate against the shared graph. Per-seat licensing is offline and signed (no phone-home — verified locally on your own metal), managed with waystone team issue.

Full guide: docs/team-server.md.

Hosted API

The default store is local SQLite — no cloud dependency, no infra to manage. For cross-machine sync without running your own server, a hosted API is also available:

• Pro ($20/mo) — unlimited projects, hosted API, 1 user
• Team ($80/mo) — unlimited projects, hosted API, up to 10 users

unbidden.ai/pricing/

Docs

• Quickstart
• MCP Server setup
• CLI Reference
• REST API
• Team Server (self-hosted) — shared Postgres graph, backend: remote, Docker Compose, per-seat licensing
• Hermes Agent integration
• Advanced Configuration — API embeddings (no PyTorch), strategy tuning, attachment extraction

License

MIT — see LICENSE