diff --git a/README.md b/README.md index 905657e..cb7af0d 100644 --- a/README.md +++ b/README.md @@ -1,104 +1,115 @@ -# MemMesh +
-**Persistent, self-improving memory for AI agents.** A local-first memory -engine in Rust: one binary that runs as a desktop component (SQLite) or a -server backend (Postgres), speaks the [Model Context Protocol](https://modelcontextprotocol.io), -and wires into your AI tools with a single command. +# ๐Ÿง  MemMesh -[memmesh.ai](https://memmesh.ai) ยท [docs](https://docs.memmesh.ai) ยท Apache-2.0 +### Persistent, local-first memory for AI agents โ€” in a single Rust binary. + +*Your agents forget everything between sessions. MemMesh gives them durable, typed, searchable memory that lives on your machine โ€” no vector database, no search cluster, no mandatory LLM calls.* + +[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE) +[![Release](https://img.shields.io/github/v/release/ThinkfleetAI/memmesh?color=success)](https://github.com/ThinkfleetAI/memmesh/releases) +[![Rust](https://img.shields.io/badge/rust-1.78%2B-orange.svg)](https://www.rust-lang.org) +[![MCP](https://img.shields.io/badge/MCP-native-8A2BE2.svg)](https://modelcontextprotocol.io) +[![Stars](https://img.shields.io/github/stars/ThinkfleetAI/memmesh?style=social)](https://github.com/ThinkfleetAI/memmesh/stargazers) + +[**memmesh.ai**](https://memmesh.ai) ยท [**Docs**](https://docs.memmesh.ai) ยท [**Releases**](https://github.com/ThinkfleetAI/memmesh/releases) + +
--- -## Why +## Why MemMesh + +Every agent framework bolts memory onto a hosted vector store and an LLM extraction call per message. That means a database to run, data leaving your machine, and a bill that scales with how much you remember. -LLM agents forget everything between sessions. MemMesh gives them a durable, -typed, scoped memory: facts, contacts, and relationships that persist, are -searchable, and improve as they're used โ€” without shipping your data to a -third party. It runs on your machine, in your infrastructure, or both with -sync between them. +MemMesh takes the opposite path: **one binary, one file, everything local.** -## Install +| | MemMesh | Typical agent-memory stack | +|---|---|---| +| **Runtime** | One Rust binary (SQLite or Postgres) | App + external vector DB (+ search service) | +| **Privacy** | Data never leaves your machine | Memories shipped to a hosted store | +| **LLM calls** | **None required** โ€” heuristic capture + a zero-LLM knowledge graph | An extraction call per message | +| **Time model** | Bi-temporal (*when it happened* vs *when you learned it*) | Flat timestamps | +| **Protocol** | MCP-native โ€” works in Claude Code, Cursor, Windsurf, Codex today | Framework-specific SDK | +| **License** | Apache-2.0, no limits | Varies | -Build from source (Rust 1.78+): +## โšก 60-second quickstart ```sh +# 1. Build (Rust 1.78+) cargo build --release --bin memmesh -# binary at ./target/release/memmesh -``` -Wire it into every AI tool on your machine in one command: +# 2. Wire it into every AI tool on your machine โ€” one command +./target/release/memmesh install -```sh -memmesh install +# 3. Watch it remember +./target/release/memmesh observe --content "Ryan prefers pnpm over npm for all projects." +./target/release/memmesh search --query "pnpm" +# โ†’ returns the stored memory, typed and timestamped ``` -That detects each supported tool, writes its MCP server config block, and -drops the agent teaching skill in the right place. Existing MCP servers in -your configs are preserved โ€” configs are merged, never replaced. +`memmesh install` detects each supported tool, merges an MCP server block into its config (your other MCP servers are untouched), and drops the teaching skill in the right place. | Tool | MCP config | Skill location | |---|---|---| | Claude Code | `~/.claude.json` | `~/.claude/skills/memmesh/SKILL.md` | | Cursor | `~/.cursor/mcp.json` | `~/.cursor/rules/memmesh/SKILL.md` | -| Windsurf | `~/.codeium/windsurf/mcp_config.json` | (MCP tool descriptions) | -| Codex CLI | `~/.codex/config.toml` | (MCP tool descriptions) | +| Windsurf | `~/.codeium/windsurf/mcp_config.json` | *(MCP tool descriptions)* | +| Codex CLI | `~/.codex/config.toml` | *(MCP tool descriptions)* | -Restart the host tool afterward so it picks up the new config. Useful flags: -`--dry-run`, `--tool ` (repeatable), `--force`, `--skill-only`, -`--mcp-only`. +Restart the host tool afterward so it reloads its config. Useful flags: `--dry-run`, `--tool ` (repeatable), `--mcp-only` (skip the skill), `--no-hooks` (skip the Claude Code auto-observe hook), `--force`. -## Usage +## ๐Ÿ› ๏ธ CLI The binary opens `~/.memmesh/memory.db` by default (override with `--db `): ```sh -# Init / re-apply migrations (safe to repeat) -memmesh migrate - -# Save a memory item -memmesh save \ - --platform plat_test --project proj_alpha \ - --type fact --scope project \ - --content "Sarah prefers email over phone" - -# Fetch by id -memmesh get mem_demo_1 - -# Search (scope/project-filtered) -memmesh search --query "Sarah" --project proj_alpha --limit 10 - -# Run as an MCP stdio server -memmesh mcp +memmesh migrate # init / re-apply migrations (safe to repeat) +memmesh observe --content "We decided to use Postgres for the memory backend." +memmesh save --platform local --project alpha --type fact \ + --content "Sarah prefers email over phone" +memmesh get # fetch by id +memmesh search --query "Sarah" --project alpha --limit 10 +memmesh mcp # run as an MCP stdio server ``` -### Tools exposed over MCP +## ๐Ÿงฐ MCP tools Underscore names are canonical; dot names are accepted as legacy aliases. +**Available in the open-source engine (fully local):** + | Tool | What it does | |---|---| -| `memory_observe` | Feed raw text; the engine decides what to save (primary write path) | -| `memory_save` | Upsert a memory item with scope, type, content, importance (rare) | +| `memory_observe` | Feed raw text; substantive statements are captured automatically (primary write path) | +| `memory_save` | Upsert a memory item with scope, type, content, importance | | `memory_recall` | Fetch by id (reinforces the item on access) | -| `memory_search` | Filter by scope/project/agent/user/session + content match | +| `memory_search` | Filter by scope / project / agent / user / session + content match | | `memory_list` | Most-recent items in a scope | -| `memory_delete` | Forget an item โ€” soft-reject (default, sync-safe) or hard delete | -| `memory_supersede` | Record a correction (old item kept for provenance) | -| `memory_stats` | Counts by type/scope/status + age span | -| `memory_extract_pending` / `memory_commit_extraction` | Client-LLM knowledge-graph extraction | +| `memory_delete` | Forget an item โ€” soft delete (default, recoverable) or hard delete | +| `memory_supersede` | Record a correction (the old item is kept for provenance) | +| `memory_stats` | Total count of stored memories | +| `memory_extract_pending` / `memory_commit_extraction` | Client-LLM knowledge-graph extraction โ€” **your** model, your key, your rate limit (the engine never calls an LLM) | + +**Hosted mode ([memmesh.ai](https://memmesh.ai)) โ€” the intelligence layer:** + +| Tool | What it does | +|---|---| | `memory_graph_reason` | Multi-hop reasoning over the knowledge graph | | `memory_query_graph` | Point-in-time (bi-temporal) edge query | | `memory_prefetch_related` | Anticipatory retrieval via spreading activation | -| `memory_build_context` | Full subject context bundle (profile + patterns + predictions) | -| `memory_predict` | Forecast a subject's next events, calibrated + with provenance | +| `memory_build_context` | Full subject-context bundle (profile + patterns + predictions) | +| `memory_predict` | Forecast a subject's next events โ€” calibrated, with provenance and honest abstention | -## Architecture +> The open-source engine is a complete, durable memory **store**. Hosted mode adds the intelligence layer โ€” calibrated prediction, behavior discovery, and graph reasoning โ€” on top of the same data. Skills for hosted-only tools degrade gracefully to `search` / `recall` on a local install. -A single Rust workspace: +## ๐Ÿ—๏ธ Architecture + +A single Rust workspace; mode is chosen at runtime, not compile time โ€” the same binary runs local (SQLite) or server (Postgres). | Crate | Purpose | |---|---| -| `core` | Domain types (`MemoryItem`, `MemoryScope`, `Contact`, โ€ฆ) + algorithms | +| `core` | Domain types (`MemoryItem`, `MemoryScope`, `Contact`, โ€ฆ) + heuristic extraction | | `storage` | `Storage` trait + `SqliteStore` + `PostgresStore` | | `embed` / `embed-server` | Embedding generation + a standalone embedding service | | `mcp` | MCP stdio protocol layer | @@ -109,10 +120,10 @@ A single Rust workspace: | `cli` | The `memmesh` binary | | `eval` | Retrieval-quality evaluation harness | -Mode is chosen at runtime, not compile time โ€” the same binary runs local -(SQLite) or server (Postgres). +## ๐Ÿค Contributing + +Issues and PRs welcome. MemMesh is Apache-2.0 and built to be embedded, extended, and self-hosted. If you're using it in a project, we'd love to hear about it. -## License +## ๐Ÿ“„ License -[Apache License 2.0](LICENSE). ยฉ 2026 ThinkFleet, Inc. and MemMesh -contributors. +[Apache License 2.0](LICENSE). ยฉ 2026 ThinkFleet, Inc. and MemMesh contributors.