winze — persistent project memory for AI coding assistants

A winze is a shaft that takes one deeper in a (data) mine

AI coding assistants start every session with a blank slate. They don't know what you decided last week, why you chose approach A over B, or what's half-finished in a branch. You end up re-explaining context, and the AI re-reads files it already analyzed.

Winze fixes this. Write planning documents as markdown files in a Plans/ directory; Winze indexes them with vector embeddings so your AI recovers full context in seconds — across sessions, across projects. A filesystem watcher keeps the index current in real time as you (or your AI) edit documents.

Quick start

1. Install Winze

• macOS (Apple Silicon): download Winze-macos-arm64.dmg and install it as an application.
• Linux / Windows / building from source: cd winze-server && make install-winze.

Requires JDK 21+ on PATH (Eclipse Temurin recommended).

The installer registers Winze with Claude Code automatically and installs the seven slash command skills (/search-plans, /index-plans, etc.). For other agents see Agent integration.

2. Set up your project

• Create a Plans folder in your project root mirroring this structure.
• Open Winze and follow the Welcome page prompt to add your project's root to its search index.
• Add Winze instructions to your CLAUDE.md (or AGENTS.md) so your agent knows how to work with your planning documents — see the CLAUDE.md guide.

3. Create your first context/plan pair

Ask your agent to create a context/plan pair using a prompt like:

In the Plans/todo folder, create two Markdown documents describing how to add a /fizbuzz endpoint to our service. The fizbuzz parameter should be a URL parameter and the only method to implement is GET. The first file is FIZBUZZ-CONTEXT.md and should include all of the contextual background information that a future Claude instance needs to successfully add the endpoint. The second one should be called FIZBUZZ-PLAN.md and should be a step-by-step plan that the future Claude will use to make the required code changes. Carefully search existing code and documentation so these files are grounded in existing facts.

You only need this level of detail the first few times. Once your agent has seen the pattern, an abbreviated prompt works fine:

Write a new context/plan document to add a /fizbuzz endpoint. The parameter should be a URL parameter and the only method to implement is GET. Search existing plans and source code for context.

The new docs should appear in Winze's search window within a second of being written — that's your confirmation that everything is wired up correctly. Shift-Cmd-P opens the command palette, and file names in search results are clickable to open files in a new tab.

Why context/plan pairs?

After the agent writes the files, read them and iterate. Direct the agent to make changes to both documents until you're satisfied it understands the task and can complete it. Then open a new session, have it read the context/plan pair, and execute the plan.

This keeps your context window small and 100% relevant to the task, which helps the agent be smarter. It also reduces token cost — each new prompt sends the entire context window back to the agent, so a lean context pays for itself with every turn.

One knowledge base, two interfaces

Your planning documents are plain markdown in Git — browse them in your editor, review them in PRs, search them on GitHub. Winze adds semantic search on top, so your AI assistant finds relevant context by meaning, not keywords. One set of files serves both audiences without duplication.

For AI agents: persistent memory, semantic search, structured metadata filters (status, type, group), and a self-maintaining index.

For humans: readable files, Git history, meaningful diffs, and a native desktop UI with live search.

Key features

• No API keys, no external services — embeddings run entirely in-JVM via inference4j (all-MiniLM-L12-v2, 384d)
• Filesystem watcher — edits appear in search results within a second, no manual indexing
• Metadata inference — status, type, group, and Jira key derived automatically from directory/filename conventions (~97% coverage)
• Multi-project support — one store indexes multiple project roots with scoped search
• Native desktop UI — live search, system tray icon, file viewer with markdown rendering, tabbed navigation (Eclipse SWT via Clojure Desktop Toolkit)
• Claude Code integration — MCP server with seven slash command skills (/search-plans, /index-plans, /recent-plans, etc.)

Why not just...

Approach	What's missing
Paste context into every prompt	Doesn't scale; you forget things; wastes tokens
Code comments	Explain what, not why or what you tried and rejected
Wiki / Confluence	AI can't search it efficiently; goes stale; separate from code
Git commit messages	Too granular; no narrative; no semantic search
AI memory features	Opaque; not version-controlled; limited capacity

Quick install

Requires JDK 21+ on PATH (Eclipse Temurin recommended). Everything else is handled automatically.

cd winze-server && make install-winze

Builds a self-contained package (jlink JRE + uberjar + Babashka), installs to ~/.local/share/winze/, registers the MCP server with Claude Code, and installs all slash command skills. The server auto-starts on first use.

See winze-server/README.md for full documentation, including the workflow guide explaining the three-layer architecture and how to use the system effectively.

Architecture

Claude Code
    │ JSON-RPC (stdio)
bb mcp-proxy.clj          ← Babashka, translates MCP to nREPL
    │ nREPL (localhost)
winze-server JVM          ← long-lived, persists between sessions
    │
clj-llm-memory            ← core library
    │
Datalevin + inference4j   ← storage + embeddings
    │
~/.local/share/winze/

Projects

winze-server — Server, MCP integration, and native UI

The application layer: nREPL server, Babashka MCP proxy, SWT desktop window with live search, and Claude Code skill definitions.

clj-llm-memory — Core library

The engine: HNSW vector index via Datalevin, markdown chunking, metadata inference, incremental reconciliation, and filesystem watching. Use this directly if you want to embed the search engine in your own application.

Requirements

• JDK 21+ on PATH — Eclipse Temurin recommended. The Clojure CLI is installed automatically if not present.
• Claude Code — for MCP registration and slash command skills
• Platform: macOS ARM64, Linux AMD64/ARM64, or Windows AMD64