Summary

cavemem addresses the problem of coding assistants forgetting information across sessions by providing a local-first, persistent memory system. It targets users of AI coding tools like Claude Code, Cursor, and Gemini CLI, enabling agents to retain context efficiently through compressed storage and fast retrieval, thereby reducing token costs and improving workflow continuity.

How It Works

The system employs hooks that trigger at session boundaries to capture agent observations. These observations are compressed using the "caveman grammar," which significantly reduces prose token count (~75%) while preserving code, paths, and identifiers verbatim. Compressed data is stored locally in SQLite, augmented with SQLite FTS5 for keyword search and an optional local vector index for semantic search. Retrieval is handled via three progressive MCP (Multi-Agent Communication Protocol) tools: search, timeline, and get_observations, allowing agents to filter and fetch data efficiently. Privacy is enhanced by stripping <private>...</private> tags and supporting path exclusion patterns.

Quick Start & Requirements

Installation is straightforward via npm: npm install -g cavemem. IDE integration is managed with commands like cavemem install for Claude Code or cavemem install --ide cursor for supported IDEs (Cursor, Gemini CLI, OpenCode, Codex). A local worker for building embeddings auto-spawns on first use but can be configured or disabled. A read-only web viewer is accessible at http://localhost:37777 via cavemem viewer.

Highlighted Details

• Compression: Achieves ~75% reduction in prose tokens while guaranteeing byte-for-byte preservation of code and paths.
• Local-First Architecture: Operates entirely locally by default, with no network or cloud dependencies required.
• Hybrid Search: Combines BM25 keyword search (SQLite FTS5) with optional local vector embeddings, tunable via search.alpha.
• Web Viewer: Provides a human-readable, read-only interface for browsing past sessions at http://localhost:37777.
• Cross-IDE Support: Offers one-command installers for seamless integration with multiple popular coding environments.

Maintenance & Community

The project shows recent commit activity. While it is part of a larger "Caveman Ecosystem," direct links to community channels (like Discord or Slack) or detailed contributor information beyond the primary author are not present in the README.

Licensing & Compatibility

cavemem is released under the permissive MIT license. This license allows for broad compatibility, including commercial use and integration within closed-source projects without significant restrictions.

Limitations & Caveats

The system relies on user configuration for privacy features like path exclusions and stripping sensitive tags. While a local embedding worker is provided, its performance and resource usage may vary, and disabling it could impact semantic search capabilities. The README does not explicitly state an alpha or beta status, but the ecosystem approach suggests ongoing development.