Rummy is a headless, metacognitive relational architecture for LLM agents. It is designed to be integrated into real-world workflows—from IDEs and CLI tools to autonomous research pipelines—where project state is complex and accuracy is non-negotiable.
While traditional agents "thrash" and fail under the weight of linear chat history, Rummy treats the LLM as a program executing on a managed memory substrate. This "Virtual Memory" architecture ensures that Rummy remains reliable in sessions that span hundreds of turns and tens of thousands of files.
Rummy provides the memory hierarchy necessary to maintain high-fidelity reasoning over unlimited-turn sessions. This is not a benchmarking "harness," but a production-grade Operating System for AI agency:
- Indexed (
<index>): Folksonomic catalog of entries the model can see at a glance. Knowns and unknowns show their full body in the tile; files and URLs show a stable identifier; streams show a tail preview. The model's working set. - Archived: Hidden but recallable. Pattern-addressable storage. The model archives entries it no longer needs in the index and pulls them back via
<get>when relevant. - The Disk (SQLite): The persistent substrate behind both — every entry, log event, prompt, and prior tool result lives in a single SQLite store, scoped per-run / per-project / global as the scheme declares.
Rummy is a headless service. It exposes a JSON-RPC over WebSocket interface, allowing it to be embedded into any client (e.g., rummy.nvim). The server manages the project state and the "Kernel" loop, while the client drives the UI and handles local proposal resolution.
Rummy is built for integration. Every <tag> the model sees is a plugin. Every URI scheme (known://, unknown://, sh://) is registered by its owner. Developers can drop custom logic into src/plugins/ to add new tools, filters, or event hooks. See PLUGINS.md for details.
Every operation in Rummy reduces to one of six verbs over a single entry contract: set / get / rm / mv / cp / update. Tools (<sh>, <search>, <known>, <unknown>, …) are plugins that compose these primitives. Three actor surfaces — model XML tags, plugin RummyContext methods, JSON-RPC client calls — speak the same grammar at the store layer.
Visibility (indexed / archived) is the model's exclusive lever. The engine never auto-promotes or auto-demotes catalog entries — knowns, unknowns, files, and streams stay where the model puts them. When the budget overflows, the engine reclaims fat replays (prior-turn <get> / <set> log bodies) and emits a 413 error:// so the model sees what was reclaimed. No chat-waterfall horizon, no spooky compaction — the model controls what it sees and what it doesn't.
Rummy turns "Not Knowing" into a formal state to be processed. By mapping Unknowns (unknown://) into verified Knowns (known://), Rummy provides a transparent, auditable trail of how the agent arrived at its conclusion.
Rummy loads configuration from exactly one directory per invocation:
- The current working directory (if it contains
.env.example). - Otherwise,
${RUMMY_HOME}(default~/.rummy).
# Set your RUMMY_HOME
export RUMMY_HOME=~/.rummy
# Install globally
npm i -g @possumtech/rummy
# Configure your environment
$EDITOR ~/.rummy/.env.example # set model aliases and keys
rummyStart the service and connect your preferred client. The server defaults to port 3044.
- Official Client: rummy.nvim (Neovim interface)
- In-process CLI:
rummy-cli(one-shot ask/act invocations against a project; seesrc/plugins/cli/) - Diagnostic Suite:
test/tbench/andtest/programbench/(autonomous diagnostic and benchmarking harnesses)
| Document | Contents |
|---|---|
| SPEC.md | Technical Specification: K/V store, packet structure, dispatch path, and lifecycle contracts. |
| PLUGINS.md | Extensibility: Hook registry, event filtering, and custom scheme registration. |
| src/plugins/ | Plugin Reference: Internal documentation for each scheme and toolset. |
| AGENTS.md | Project roadmap, planning history, and architectural lessons. |
Rummy: The Managed Operating System for AI Agency.