From e61fb8fcfc7df74cdd3f0e31a2ebb3ca94715aa0 Mon Sep 17 00:00:00 2001 From: Toni Nowak Date: Tue, 23 Jun 2026 02:33:49 +0200 Subject: [PATCH] chore(release): 2.5.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Storage-agnostic features ported from upstream neural-memory (#31–34) plus a full docs sync. Features (#31–34): - chat-heavy config preset; concept-extraction stats + opt-in verbose_extraction (#31) - MCP tools smem_offload / smem_inflate / smem_situation; recall prefer_recent (#31) - plugin hook dedup (#169) + [brain] config extras pass-through (#168) (#31) - case-insensitive tag matching (#33) - lighter PostToolUse hook — stdlib-only, noise filter, lock-safe append, Codex id (#32) - dashboard Storage tab rebuilt for SurrealDB + GET /api/dashboard/storage/status (#34) Docs: - changelog reconciliation (surreal-memory 2.x line + link to root for upstream history) - API server endpoint doc; tool count 53 -> 56 across reference docs - rebranded promo package + new vs-neural-memory comparison Version bumped 2.4.0 -> 2.5.0 across pyproject, __init__, version test, and all npm packages. --- CHANGELOG.md | 47 +++ README.md | 4 +- docs/api/server.md | 24 ++ docs/changelog.md | 382 +++++++++++++++++- docs/contributing.md | 2 +- docs/getting-started/quickstart.md | 2 +- docs/guides/mcp-server.md | 11 +- docs/guides/pro-quickstart.md | 4 +- docs/promo/devto-article.md | 99 +++-- docs/promo/discord-anthropic.md | 34 +- docs/promo/hackernews.md | 10 +- docs/promo/reddit-claudeai.md | 58 +-- docs/promo/reddit-localllama.md | 62 +-- docs/promo/vs-neural-memory.md | 51 +++ .../surreal-memory-client/package-lock.json | 4 +- .../surreal-memory-client/package.json | 2 +- integrations/surrealmemory/package-lock.json | 4 +- integrations/surrealmemory/package.json | 2 +- pyproject.toml | 2 +- src/surreal_memory/__init__.py | 2 +- tests/unit/test_health_fixes.py | 2 +- vscode-extension/package-lock.json | 4 +- vscode-extension/package.json | 2 +- 23 files changed, 683 insertions(+), 131 deletions(-) mode change 100755 => 100644 docs/changelog.md create mode 100644 docs/promo/vs-neural-memory.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 09f806f4..e3b6e7b1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [2.5.0] — 2026-06-23 + +Storage-agnostic improvements ported from upstream +[nhadaututtheky/neural-memory](https://github.com/nhadaututtheky/neural-memory) and adapted +to the SurrealDB-only backend, plus two follow-up fixes. + +### Added + +- **`chat-heavy` config preset** — a conversational-agent profile (Telegram/Discord/Slack): + faster decay, recency-biased recall, compact context. Apply with `smem config preset chat-heavy`. (#31) +- **`smem_offload` / `smem_inflate` MCP tools** — store a large tool result as an ephemeral + neuron (24h TTL) and get back a compact `ref_id` + summary, then drill into the full content + on demand. Keeps bulky tool output out of the agent's context. (#31) +- **`smem_situation` MCP tool** — one-shot snapshot of the working situation (active session + task, top recent decisions, open blockers), so an agent can resume context without chaining + `smem_recap` + multiple `smem_recall` calls. (#31) +- **`prefer_recent` recall flag** — re-ranks matched fibers newest-first (by `time_end`, falling + back to `created_at`) for "current state" queries; off by default. (#31) +- **`verbose_extraction` flag on `smem_remember`** — surfaces concept-extraction observability + counters (`dropped_short` / `dropped_noise` / `dropped_duplicate_entity`) so you can see why + concept neurons were filtered; off by default. (#31) +- **`[brain]` config extras pass-through** — `BrainSettings` now forwards any `[brain]` key in + `config.toml` that maps to a real `BrainConfig` field, so new tuning knobs become + config-controllable without a parallel setting each, and already-stored brains pick them up + on load. (#31, upstream #168) +- **Case-insensitive tag matching** — tags are normalized (lowercased) at every write and read + boundary, so `KB`, `kb`, and `Kb` all match. (#33) +- **Dashboard Storage tab rebuilt for SurrealDB** — the Storage tab now shows live SurrealDB + backend status (URL, namespace, database, connection health, and neuron/fiber/synapse counts) + via the new `GET /api/dashboard/storage/status` endpoint. (#34) + +### Changed + +- **Lighter PostToolUse hook** — rewritten to be stdlib-only (no heavy imports on the hot path), + with a noise-tool fast-path filter, lock-safe JSONL append (POSIX `flock` / Windows fallback), + and `CODEX_SESSION_ID` support alongside `CLAUDE_SESSION_ID`. (#32) +- **Plugin hook de-duplication** — when running as the Claude Code plugin, first-time init skips + `setup_hooks_claude()` so hooks are not registered twice (the plugin's own `hooks.json` owns + registration). (#31, upstream #169) +- **MCP tool count is now 56** (was 53) with the three new agent-ergonomics tools above. (#31) + +### Removed + +- **Dead multi-backend dashboard Storage UI** — the legacy SQLite↔InfinityDB migration components + (`MigrationCard` / `MigrationProgress`) were removed; surreal-memory is SurrealDB-only, so the + migration flow no longer applies. (#34) + ## [2.4.0] — 2026-06-22 All changes in this release were contributed by [@RobertSigmundsson](https://github.com/RobertSigmundsson), who adopted surreal-memory as the production memory engine of the Uruboros multi-agent swarm. Huge thanks. diff --git a/README.md b/README.md index 6899e959..0ea07f20 100644 --- a/README.md +++ b/README.md @@ -106,7 +106,7 @@ smem recall "auth bug" ## 3 Tools. That's It. -53 MCP tools are available, but you only need three: +56 MCP tools are available, but you only need three: | Tool | What it does | |------|-------------| @@ -122,7 +122,7 @@ Everything else — sessions, context loading, habit tracking, maintenance — w ``` ┌──────────────────────────────┐ - │ MCP Server (53 tools) │ + │ MCP Server (56 tools) │ └──────────┬───────────────────┘ │ ┌──────────▼───────────────────┐ diff --git a/docs/api/server.md b/docs/api/server.md index 6f4a9fa5..805fc3d6 100755 --- a/docs/api/server.md +++ b/docs/api/server.md @@ -452,6 +452,30 @@ Get brain file paths and disk usage. } ``` +### Storage Status + +#### GET /api/dashboard/storage/status + +Get the active storage backend and live connection status (SurrealDB-only since v2.0.0). +Powers the dashboard **Storage** tab. + +**Response:** + +```json +{ + "backend": "surrealdb", + "url": "http://localhost:8001", + "namespace": "surreal_memory", + "database": "default", + "healthy": true, + "active_brain": "my-brain.v2", + "neuron_count": 0, + "fiber_count": 0, + "synapse_count": 0, + "health_grade": "F" +} +``` + ### Telegram Status #### GET /api/dashboard/telegram/status diff --git a/docs/changelog.md b/docs/changelog.md old mode 100755 new mode 100644 index d02f3828..6d42e819 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -5,11 +5,37 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -> **Source of truth:** [`CHANGELOG.md`](https://github.com/acidkill/surreal-memory/blob/main/CHANGELOG.md) in the repository root. -> This page mirrors that file for the MkDocs site. +> **Source of truth:** [`CHANGELOG.md`](https://github.com/acidkill/surreal-memory/blob/main/CHANGELOG.md) +> in the repository root. This page covers the **surreal-memory** (post-fork) release line. The full +> history — including the pre-fork upstream [neural-memory](https://github.com/nhadaututtheky/neural-memory) +> v4.x → v0.x — lives in that root file. ## [Unreleased] +## [2.5.0] — 2026-06-23 + +### Added + +- **`chat-heavy` config preset** for conversational agents (fast decay, recency-biased, compact). (#31) +- **`smem_offload` / `smem_inflate` / `smem_situation` MCP tools** — ephemeral tool-output offload + + one-shot session snapshot (agent ergonomics). (#31) +- **`prefer_recent` recall flag** and **`verbose_extraction` remember flag**. (#31) +- **`[brain]` config extras pass-through** so new `BrainConfig` knobs are config-controllable. (#31, upstream #168) +- **Case-insensitive tag matching** at all write/read boundaries. (#33) +- **Dashboard Storage tab rebuilt for SurrealDB** — live backend status (URL, namespace, database, + health, counts) via new `GET /api/dashboard/storage/status`. (#34) + +### Changed + +- **Lighter PostToolUse hook** (stdlib-only, noise filter, lock-safe append, Codex session id). (#32) +- **Plugin hook de-duplication** — plugin installs no longer double-register hooks. (#31, upstream #169) +- **MCP tool count is now 56** (was 53). + +### Removed + +- **Dead dashboard Storage migration UI** (`MigrationCard` / `MigrationProgress`) — SurrealDB-only, + the migration flow was removed. (#34) + ### Maintenance - **Repository file-permission normalization** (`a4f27d0`, 2026-05-05): 963 tracked files had @@ -17,6 +43,352 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 `core.fileMode` mismatch on the host filesystem. Zero content changes — this commit restores the intended permission state so future diffs reflect only real code changes. +## [2.4.0] — 2026-06-22 + +All changes in this release were contributed by [@RobertSigmundsson](https://github.com/RobertSigmundsson), who adopted surreal-memory as the production memory engine of the Uruboros multi-agent swarm. Huge thanks. + +### Added + +- `get_synapses(..., limit=None)` — optional cap on returned synapses, mirroring `find_neurons`. Bounds memory/latency on dense graphs (consolidation, replay). (#26) +- `GeminiEmbedding` honours `GOOGLE_GEMINI_BASE_URL` / `GOOGLE_GEMINI_API_VERSION` for gateway/proxy routing. (#27) + +### Fixed + +- **Activation persistence restored:** `neuron_state` records are addressed as `neuron_state:state_` on read/update/delete, matching the writer in `add_neuron`. The missing `state_` prefix made every state read miss and every update a silent no-op, leaving the activation→decay→tiering→consolidation loop dormant. (#29, re-scoped from #16) +- Never auto-prune pinned isolated (orphan) neurons; the pinned guard now covers both the orphan and dead-neuron prune paths. (#17) +- Pin `surrealdb` SDK to `>=2.0.0,<3.0.0`; the 2.x API is required and the old `>=0.4.0` floor allowed incompatible installs with opaque `AttributeError`s. (#18) +- `GeminiEmbedding.embed_batch` wraps each text in its own content, fixing N-texts→1-embedding under `google-genai >= 2.0` (which broke `reindex`). (#19) +- Tolerant neuron-type parsing; an unknown stored `type` falls back to `concept` with a warning instead of breaking recall for the whole brain. (#20) +- Remove leftover literal `{{}}` in nine `SCHEMA_SQL` DEFAULT clauses (invalid SurrealQL, so the DEFAULTs silently never applied). (#21) +- Default `synapse.brain_id` to `'default'` (was undeclared → NONE-coercion when omitted). (#22) +- `_to_surreal_id` strips an existing table prefix to prevent `neuron:neuron:…` id doubling (all three copies). (#23) +- Add `FORWARD`/`BACKWARD` to the `Direction` enum so the `'forward'` default in `_row_to_synapse` is valid (was a latent `ValueError`). (#24) +- Drop the write-only `connects_to` edge table; declare `source_id`/`target_id` on the synapse table and repoint the source/target indexes at those populated columns (Discussion #15, option A). (#25) + +## [2.3.2] — 2026-06-01 + +### Fixed +- **SurrealDB auth fail-fast** — `SurrealDBStorage.initialize()` and `_reconnect()` now + raise `StorageAuthError` (actionable) instead of propagating the raw SDK + `NotAllowedError`. The MCP server surfaces this as JSON-RPC code `-32001` with a + hint pointing to `SURREALDB_PASS` and `smem doctor --fix`, replacing the opaque + `-32000 "failed unexpectedly"` that made bad-credential failures invisible. +- **Default password unified** — the silent default `SURREALDB_PASS=root` (which never + matched the Docker default `surrealmemory`) is replaced by a single source of truth + in `storage/surrealdb/connection.py`. Both `store.py` and `unified_config.py` now + derive the default from this module, eliminating the drift that caused clean-install + auth failures. + +### Added +- **`storage/surrealdb/connection.py`** (new module) — `SurrealSettings.from_env()`, + `StorageAuthError`, `is_credential_error()`, `build_mcp_env()`; single source of + truth for all SurrealDB connection defaults. +- **Claude Desktop MCP support** — `smem init` and `smem setup mcp` now write the + `surreal-memory` entry (including the full `env` block with `SURREALDB_PASS`) to + `claude_desktop_config.json` on Linux, macOS, and Windows. Existing entries without + `env` are backfilled automatically. +- **`env` block in all MCP configs** — `find_smem_command()` always returns an `env` + dict so newly written Claude Code and Cursor configs include SurrealDB connection + variables, preventing the "empty env" bug on clean installs. +- **`smem doctor` SurrealDB checks** — two new diagnostic checks: + - `SurrealDB connection` (TIER_CORE): live auth test with 5-second timeout; FAIL + with actionable fix on `StorageAuthError`. + - `MCP env completeness` (TIER_RECOMMENDED): verifies `SURREALDB_PASS` is present + in the `env` block of each MCP client config. + - `smem doctor --fix` backfills missing env in all detected client configs. +- **`_warn_missing_surreal_pass()`** — one-time warning when `storage=surrealdb` is + active but `SURREALDB_PASS` is unset. + +### Changed +- `_check_brain` and `_check_schema_version` in `smem doctor` now return `SKIP` + (not `FAIL`) when the SurrealDB backend is active — those checks are SQLite-only. +- `setup_mcp_claude()` uses JSON write path exclusively (the `claude mcp add` CLI + does not support the `env` block). Behaviour from the user perspective is identical. +- `SURREALDB_PASS` default (`surrealmemory`) documented in installation and + contributing guides. + +## [2.3.1] — 2026-05-31 + +### Fixed +- **Dashboard ⇄ CLI metric parity** — `SurrealDBStorage.get_enhanced_stats` now + returns a `synapse_stats` block (per-type counts), so `DiagnosticsEngine` + computes `diversity` and `recall_confidence` on the SurrealDB backend exactly + as it does on SQLite. Previously both were `0` on SurrealDB, so the dashboard + and the `smem` CLI reported different health grades (e.g. F vs D) for the same + brain. +- **Consistent brain grade across endpoints** — `/api/dashboard/brains` now runs + diagnostics like `/api/dashboard/stats`, so the Brains table and the stats + cards report the same grade. Per-brain analysis runs sequentially to avoid + racing the shared SurrealDB storage singleton. +- **Resilient SurrealDB connection** — `SurrealDBStorage._query` re-authenticates + and retries once on an expired/closed connection (HTTP 401), so long-lived MCP + and CLI processes survive SurrealDB restarts and root-token expiry instead of + failing every subsequent call. +- **Accurate orphan rate** — `DiagnosticsEngine.analyze` pins the storage brain + context before its reads, preventing a false high orphan rate when multiple + brains are analyzed concurrently. + +### Added +- **SQLite misconfiguration guard** — emit a loud, one-time warning when the + active storage backend resolves to SQLite, with a targeted message when + SurrealDB connection vars are set. surreal-memory targets SurrealDB; this + surfaces the "memories silently written to a local SQLite brain that diverges + from the SurrealDB the dashboard reads" footgun instead of failing silently. + +### Changed +- Pin the `surrealdb` Docker image to `v3.1.1` in `docker-compose.surrealdb.yml`. + +## [2.3.0] — 2026-05-29 + +### Added +- **SurrealDB tool-event storage** — new `tool_events` table (schema v6) brings the + SurrealDB backend to parity with SQLite. Powers the dashboard **Tool Stats** page + and consolidation's tool-usage pattern mining on the SurrealDB backend (previously + raised `AttributeError`). + +### Fixed +- **Dashboard is fully free** — removed leftover Pro-tier gating that survived the + SurrealDB-only switch. **Evolution** and **Visualize** no longer show a "PRO FEATURE" + overlay, the **Embedding Provider** settings are editable (no 403), and **Settings → + General** reports a `FULL` license with no upgrade prompt. +- **Storage page** — rebuilt for the SurrealDB-only model. It now shows the active + SurrealDB backend, neuron/synapse/fiber counts, and tier distribution from the live + `/stats` + `/tier-stats` endpoints, instead of calling the removed `/storage/status` + endpoint that left the page blank. +- **Brain lookup by name** — `SurrealDBStorage.get_brain` now matches the `name` field, + fixing an orphan-row leak where the bootstrap re-created a fresh brain on every start + (active brain reported 0 neurons even when the store held data). +- **Dashboard brain enumeration** — `/api/dashboard/stats` and `/api/dashboard/brains` + now list brains from the active SurrealDB store (`list_available_brains`) instead of + only local SQLite fixture files, so the dashboard no longer shows zero brains. + +### Changed +- `UnifiedConfig.is_pro()` always returns `True` and `/api/dashboard/license` reports the + `full` tier — Surreal-Memory is fully free; every feature is unlocked for everyone. +- A fresh process now honors `SURREAL_MEMORY_STORAGE` before a `config.toml` exists, so it + no longer caches a SQLite singleton while the environment asks for SurrealDB. + +## [2.2.0] — 2026-05-28 + +### Added +- **Embedding env overrides** — the unified config now honors + `SURREAL_MEMORY_EMBEDDING_ENABLED` / `_PROVIDER` / `_MODEL` / + `_SIMILARITY_THRESHOLD` (precedence: env > `config.toml` > default), so the + MCP server and CLI follow the embedding provider set in their environment. +- **`smem reindex`** — (re)embed a brain's neurons with the effective provider. + Flags: `--dry-run`, `--missing-only` (default) / `--all`, `--batch-size`; + idempotent and fail-soft per neuron. + +### Changed +- **Effective config wins** — embedding `enabled`/`provider`/`model` now resolve + from the effective config (`config.toml` + env) instead of the stale stored + `brain.config`. Fixes embeddings silently staying disabled after a user edits + their config/env. `smem_health` now reports the effective embedding state. + +### Performance +- The Stop hook no longer loads a local `sentence-transformers` model on every + session end (it was the dominant session-save latency). Semantic dedup uses a + local Ollama server when one is running, otherwise it is skipped. + +## [2.1.0] — 2026-05-28 + +### Added +- **Project-aware memory hooks** — SessionStart, PreCompact, and Stop hooks scope + captured memories to the current project (git repo basename as `project_id`); + SessionStart injects only the current project's memories. +- **Task-context hook** — new `smem-hook-task-context` entry point persists a rich, + structured per-task note as one project-scoped `context` memory. +- **SurrealDB Project entity** — `add_project` / `get_project` / `get_project_by_name` + / `list_projects` / `update_project` / `delete_project` restored on the SurrealDB + backend (parity broken by the v2.0.0 SurrealDB-only refactor); new `project` table, + schema version 5. +- `get_project_memories` declared on the `NeuralStorage` base interface. + +### Fixed +- **Connection close** — `SurrealDBStorage.close()` tolerates transports that don't + implement `close()` (the HTTP connection raises `NotImplementedError`), fixing a + long-running MCP server degrading to "No brain configured". +- **CLI regression** — restored `surreal_memory/utils/sandbox.py`; `smem` no longer + fails with `ModuleNotFoundError` (regression from the v2.0.0 refactor). +- **Embedding pipeline hardening** — retry/backoff, embedding-capability probe, and + removal of a decommissioned default model. +- **Latent recall bug** — save hooks persist the verbatim text as the fiber summary, + so SessionStart actually injects context (previously `fiber.summary`/`essence` were + always `None`). +- Cross-backend parity test fixture (`connect()` → `initialize()`, and skip when the + optional `surrealdb` package is absent). + +### Documentation +- README: new **Embeddings** section (Gemini `gemini-embedding-001` recommended; local + `sentence-transformers` `all-MiniLM-L6-v2` / `paraphrase-multilingual-MiniLM-L12-v2` + as the no-API-key fallback; Ollama / OpenAI / OpenRouter; `auto` detection). +- Fixed rename-rot ("What's Different From NeuralMemory?", `~/.neuralmemory` migration) + and corrected counts: 15 memory types, 41 synapse types, 5500+ tests. +- INSTALL_PROMPT: fixed stale repository URLs; Gemini recommended (not required) with a + documented local no-key path. +- `.env.example`, `AGENTS.md`, `CONTRIBUTING.md` corrections. + +## [2.0.0] — 2026-05-27 + +### Removed — InfinityDB Pro chain + SQLite/InMemory demoted to test fixtures (BREAKING) + +Surreal-Memory is now **SurrealDB-only** on the public surface. The +InfinityDB Pro plugin chain is gone; SQLite and InMemory remain in the +tree but only as internal test infrastructure — they are no longer +documented, no longer offered through the CLI, and no longer reachable +through any public configuration path. + +Deletions: +- `src/surreal_memory/cli/commands/migrate.py` (no alternative backends + to migrate to). +- `tests/unit/test_infinitydb_integration.py`. +- `tests/unit/test_storage_migration_api.py`. +- ~400 lines of Storage Management code in + `src/surreal_memory/server/routes/dashboard_api.py`: + `MigrationJobStatus`, `StorageStatusResponse`, + `StartMigrationRequest`, `SetBackendRequest`, the + `GET /storage/status`, `POST /storage/migrate`, + `GET /storage/migrate/{job_id}`, `POST /storage/backend` endpoints, + `_run_migration_task`, `_open_sqlite_storage`, + `_open_infinitydb_storage`. + +Code surgery: +- `src/surreal_memory/cli/main.py`: stopped importing/registering + `migrate`. +- `src/surreal_memory/cli/commands/storage.py`: rewritten. Only + `smem storage status` remains; it probes the SurrealDB connection + instead of describing SQLite/InfinityDB files. `storage switch` is + gone — nothing to switch between. +- `src/surreal_memory/cli/commands/shared.py`: removed the + "Pro activated -> upgrade to InfinityDB" hint block. +- `src/surreal_memory/engine/consolidation.py`: removed + `ConsolidationStrategy.SMART_MERGE` and `_smart_merge_pro`. +- `src/surreal_memory/engine/retrieval.py`: `"cone"` strategy now logs + a debug message and falls back to classic activation. +- `src/surreal_memory/mcp/stats_handler.py`, + `src/surreal_memory/mcp/sync_handler.py`, + `src/surreal_memory/server/app.py`: removed every "Pro tip: + InfinityDB ..." upsell. +- `src/surreal_memory/unified_config.py`: removed + `_get_infinitydb_storage`, the `infinitydb` dispatch branch, and the + InfinityDB-directory fall-through in `list_brains()`. +- `src/surreal_memory/storage/factory.py`: dropped `_try_pro_storage`. +- `src/surreal_memory/plugins/__init__.py`, + `src/surreal_memory/plugins/base.py`, + `src/surreal_memory/plugins/community.py`: dropped + `get_storage_class()`. + +Test-only surface markings: +- `src/surreal_memory/storage/sqlite_store.py` and + `src/surreal_memory/storage/memory_store.py` now carry an explicit + TEST FIXTURE ONLY header so contributors don't mistake them for + production paths. + +Config and docs: +- `.env.example`: `SURREAL_MEMORY_STORAGE=surrealdb` is uncommented and + the comment explains that `sqlite` is not a production option. +- `docs/landing/pro.md`: dropped the InfinityDB row from the backend + table. +- `ROADMAP.md`: current-state line updated. +- `dashboard/src/i18n/en.json` + `vi.json`: dropped + `storage.infinitydb*` / `enableInfinitydb` / migration UI strings. +- `docs/getting-started/cli-reference.md`, `docs/api/mcp-tools.md`: + regenerated. + +Verification: +- `ruff check src/ tests/` clean. +- `mypy src/ --ignore-missing-imports` clean (334 files). +- `pytest --co tests/unit`: 5515 tests collected, zero import errors. +- `pytest test_unified_config + test_dx_wizard + test_brain_isolation + + test_health_fixes`: 93/93 passed locally. + +**BREAKING CHANGE:** anyone running the Pro InfinityDB chain on v1.x +must export their brain to JSON and re-import on SurrealDB before +upgrading. `smem migrate` and `smem storage switch` are gone — point +users at `docker-compose.surrealdb.yml` instead. + +### Removed — FalkorDB and PostgreSQL backends (BREAKING) + +Surreal-Memory is **SurrealDB-only** from v2.0.0 onwards. The opt-in +FalkorDB and PostgreSQL backends added in upstream v4.7 are gone: + +- Deleted `src/surreal_memory/storage/falkordb/` (8 mixin files + store). +- Deleted `src/surreal_memory/storage/postgres/` (11 mixin files + store). +- Deleted `docker-compose.falkordb.yml` and `docker-compose.postgres.yml`. +- Deleted `scripts/postgres-init.sh`. +- Deleted FalkorDB integration test `tests/integration/test_falkordb_spreading.py`. +- Deleted FalkorDB storage tests in `tests/storage/test_falkordb_*.py` (5 files) + and the entire `tests/storage/postgres/` suite (5 files + conftest). +- Deleted `tests/unit/test_postgres_migration.py`. + +Code paths trimmed: + +- `pyproject.toml`: dropped `[project.optional-dependencies] falkordb` and + `postgres` extras (and the matching ruff per-file-ignores rule). +- `src/surreal_memory/unified_config.py`: removed `FalkorDBConfig`, + `PostgresConfig`, `_get_falkordb_storage`, `_get_postgres_storage`, the + cached module globals, the TOML serializers, and the dispatch branches. + `_VALID_STORAGE_BACKENDS` is now `{"sqlite", "surrealdb"}` (InfinityDB + remains available via the Pro plugin). +- `src/surreal_memory/utils/config.py`: dropped `falkordb_*` fields. +- `src/surreal_memory/storage/__init__.py`: removed lazy `__getattr__` + branches for `FalkorDBStorage` / `PostgreSQLStorage`. +- `src/surreal_memory/cli/commands/migrate.py`: rewritten — only + `infinitydb` and `sqlite` (no-op) targets remain; FalkorDB/Postgres + targets emit a deprecation hint pointing to docker-compose.surrealdb.yml. +- `src/surreal_memory/cli/commands/storage.py`: help text reads + "SQLite, SurrealDB, InfinityDB" only. +- `docker-compose.yml`: removed the `falkordb` optional service; readers + are routed to `docker-compose.surrealdb.yml`. +- `.env.example`: removed `FALKORDB_*` block; storage options list shows + `sqlite, surrealdb`. + +Docs synced: + +- `ROADMAP.md`: replaced "PostgreSQL Backend Parity" milestone with + "SurrealDB Backend Parity"; updated current-state line and the C1 + tiered storage section. +- `docs/contributing.md`, `docs/FAQ.md`, `docs/landing/pro.md`, + `docs/promo/reddit-localllama.md`: backend table and prose updated to + reflect the new surface. +- `docs/getting-started/cli-reference.md`: regenerated from the new + `smem migrate` signature. + +**Migration:** if you were running on PostgreSQL or FalkorDB on v1.x, +export your brain to JSON before upgrading and re-import on SurrealDB +(or stay on v1.x — that line is still supported for one minor release). + +### Fixed — Concept Neuron Noise Filtering (#156) + +Short and casual text no longer creates low-signal concept neurons that pollute +recall context. `ExtractConceptNeuronsStep` now: + +- Raises min keyword length from 3 to 4 chars (filters `AI`, `OS`, `It`) +- Scales concept floor from 5 to 3 for content under 100 chars +- Skips keywords already captured as entity neurons (avoids duplicates) +- Filters known noise words (`use`, `run`, `new`, `got`, etc.) + +Aligns with the F2 Fiber Precision & Density roadmap item. + +### Fixed — Advisory hints stripped from machine output (#155) + +CLI update notices are now skipped for machine-oriented commands +(`context`, `recall`, `stats`, `status`) and any invocation with `--json`. +MCP `strip_hints` now strips advisory fields even in non-compact mode. +Adds an Agent Memory Governance guide. + +### Added — Contributor dev diagnostics (#154) + +`smem doctor --dev` now reports source checkout detection, editable install +status, dev dependencies, and checkout/package version parity for +contributors working from a source checkout. + +### Fixed — Coroutine warning on sandbox fail-fast (#153) + +CLI commands that fail fast in restricted sandboxes no longer emit +`RuntimeWarning: coroutine was never awaited`. The unawaited command +coroutine is now explicitly closed before re-raising the sandbox exit. + ## [1.0.0] — 2026-05-04 First stable release of **surreal-memory** as an independent PyPI package. This version forks from @@ -59,3 +431,9 @@ via the bundled community plugin. - **150+ new parametrised tests** across four new test files covering `get_project_memories` parity, `suggest_memory_type` coverage (128 tests), remember-handler all-types (19 tests), and SurrealDB typed-memory integration (31 tests, skipped without `SURREALDB_URL`). + +--- + +> **Earlier history.** Releases before the fork (upstream neural-memory **v4.53.4 → v0.x**) are not +> repeated here. See the full [`CHANGELOG.md`](https://github.com/acidkill/surreal-memory/blob/main/CHANGELOG.md) +> in the repository root. diff --git a/docs/contributing.md b/docs/contributing.md index e3ec0f0e..0fba55a3 100755 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -216,7 +216,7 @@ src/surreal_memory/ │ ├── surrealdb/ # SurrealDB backend (primary — 163 methods across 10 mixins) │ ├── sqlite_*.py# SQLite backend (default local) │ └── surrealdb/ # SurrealDB backend (recommended) -├── mcp/ # MCP server for Claude (53 tools, ~30 handler files) +├── mcp/ # MCP server for Claude (56 tools, ~30 handler files) ├── server/ # FastAPI REST server + dashboard static files ├── cli/ # Command-line interface (smem / surreal-memory) ├── plugins/ # Community plugin (bypasses Pro feature gates) diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index a03ea0a0..de0b5a3b 100755 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -3,7 +3,7 @@ This guide walks you through Surreal-Memory setup and usage in 5 minutes. !!! tip "3 tools you need" - Surreal-Memory has 53 tools, but you only need three: **`smem_remember`**, **`smem_recall`**, and **`smem_health`**. The agent handles the other 50 automatically. See [all tools](../guides/mcp-server.md#available-tools). + Surreal-Memory has 56 tools, but you only need three: **`smem_remember`**, **`smem_recall`**, and **`smem_health`**. The agent handles the other 53 automatically. See [all tools](../guides/mcp-server.md#available-tools). ## Why Surreal-Memory? diff --git a/docs/guides/mcp-server.md b/docs/guides/mcp-server.md index d21e1785..c891903f 100755 --- a/docs/guides/mcp-server.md +++ b/docs/guides/mcp-server.md @@ -615,9 +615,9 @@ Surreal-Memory is lightweight — it won't slow down your editor. ## Available Tools -**3 tools you need. 42 the agent handles automatically.** +**3 tools you need. 53 the agent handles automatically.** -53 tools are available, but most users only interact with three: +56 tools are available, but most users only interact with three: ### Essential (You Use These) @@ -642,6 +642,9 @@ These tools fire automatically via MCP instructions and hooks — you don't need | `smem_stats` | On demand — brain statistics | | `smem_tool_stats` | On demand — tool usage analytics | | `smem_alerts` | On health check — surfaces warnings | +| `smem_situation` | On resume — one-shot snapshot (active session, recent decisions, open blockers) | +| `smem_offload` | When tool output is large — stores it as an ephemeral ref + summary | +| `smem_inflate` | On demand — restores the full content of an offloaded ref | ### Power User (Opt-In) @@ -697,7 +700,7 @@ These tools fire automatically via MCP instructions and hooks — you don't need ## Tool Tiers -By default all 53 tools are exposed on every API turn. If you want to reduce token overhead, configure a **tool tier** in `~/.surrealmemory/config.toml`: +By default all 56 tools are exposed on every API turn. If you want to reduce token overhead, configure a **tool tier** in `~/.surrealmemory/config.toml`: ```toml [tool_tier] @@ -722,7 +725,7 @@ smem config tier full # reset to full - **minimal** — `remember`, `recall`, `context`, `recap` - **standard** — minimal + `todo`, `session`, `auto`, `eternal` -- **full** — all 53 tools +- **full** — all 56 tools > Hidden tools remain callable — only the schema listing changes. If the AI model already knows a tool name, it can still call it even when the tool is not exposed in `tools/list`. diff --git a/docs/guides/pro-quickstart.md b/docs/guides/pro-quickstart.md index 27affcaa..1fdaed98 100755 --- a/docs/guides/pro-quickstart.md +++ b/docs/guides/pro-quickstart.md @@ -182,10 +182,10 @@ Sync uses **Merkle delta** — only changes are transmitted. A brain with 100K n | Recall method | Keyword matching | Semantic similarity + graph traversal | | Consolidation | O(N²) brute force | O(N x k) Smart Merge | | Compression | Text-level trimming | 5-tier vector lifecycle | -| MCP tools | 53 tools | 53 tools + cone_query, tier_info, pro_merge | +| MCP tools | 56 tools | 56 tools + cone_query, tier_info, pro_merge | | Setup | Built-in, zero config | Requires SurrealDB instance | -**Everything stays the same.** All 53 MCP tools work with both backends. Your existing memories are preserved — when you switch to SurrealDB, they're auto-migrated on first startup. +**Everything stays the same.** All 56 MCP tools work with both backends. Your existing memories are preserved — when you switch to SurrealDB, they're auto-migrated on first startup. --- diff --git a/docs/promo/devto-article.md b/docs/promo/devto-article.md index 75f5ec8c..aa7d873d 100755 --- a/docs/promo/devto-article.md +++ b/docs/promo/devto-article.md @@ -27,23 +27,24 @@ When you ask "why did the outage happen?", it doesn't just find text containing ### RAG vs Spreading Activation | Aspect | RAG / Vector Search | Surreal-Memory | -|--------|---------------------|---------------| +|--------|---------------------|----------------| | Model | Search engine | Human brain | | LLM/Embedding | Required | Optional — core recall is pure graph traversal | | Query | "Find similar text" | "Recall through association" | -| Relationships | None (just similarity) | Explicit: `CAUSED_BY`, `LEADS_TO`, `RESOLVED_BY` | +| Relationships | None (just similarity) | Explicit: `CAUSED_BY`, `LEADS_TO`, `RESOLVED_BY`, `CONTRADICTS` | | Multi-hop | Multiple queries | Natural graph traversal | -| API Cost | ~$0.02/1K queries | $0.00 — fully offline | +| API Cost | ~$0.02/1K queries | $0.00 — no API keys needed for core operations | ## How It Works ### 1. Encoding When you tell the AI to remember something, Surreal-Memory: -- Extracts entities, keywords, temporal markers -- Creates typed neurons (ENTITY, CONCEPT, ACTION, TEMPORAL, etc.) -- Creates typed synapses between them (24 relationship types) +- Extracts entities, keywords, and temporal markers +- Creates typed neurons (ENTITY, CONCEPT, ACTION, TEMPORAL, and more) +- Creates typed synapses between them (41 explicit relationship types) - Groups related neurons into a Fiber (episodic memory bundle) +- Persists everything in SurrealDB — document + graph + vector in one engine ### 2. Retrieval (Spreading Activation) @@ -56,74 +57,112 @@ When you recall: This naturally handles multi-hop queries. "Who suggested the thing that caused the outage?" follows the chain without explicit graph queries. -### 3. Consolidation +### 3. Consolidation (Sleep Cycle) -Memories have a lifecycle: -- **Decay**: unused synapses weaken over time -- **Reinforcement**: recalled memories get stronger -- **Pruning**: orphan neurons (no connections) get cleaned up -- **Merging**: duplicate information gets consolidated +Memories have a full lifecycle modelled on human cognition: +- **Decay**: unused synapses weaken over time (Ebbinghaus forgetting curve) +- **Reinforcement**: recalled memories get stronger (Hebbian learning) +- **Pruning**: orphan neurons with no connections get cleaned up +- **Merging**: duplicate information is consolidated +- **Dreaming**: a sleep consolidation phase (ENRICH / PRUNE / MERGE / DREAM) compresses and reorganises the graph through 5-tier compression -## 50 MCP Tools +## 56 MCP Tools -Surreal-Memory exposes 53 tools via the [Model Context Protocol](https://modelcontextprotocol.io/): +Surreal-Memory exposes **56 tools** via the [Model Context Protocol](https://modelcontextprotocol.io/). The 3-tool core drives daily use; the rest fire automatically or on demand: | Tool | What it does | |------|-------------| | `smem_remember` | Store a memory with automatic extraction | | `smem_recall` | Retrieve memories through spreading activation | +| `smem_health` | Health diagnostics with actionable recommendations | | `smem_context` | Load recent memories at session start | | `smem_explain` | Show WHY two concepts are connected (BFS path) | | `smem_habits` | Detect recurring patterns in your workflow | -| `smem_consolidate` | Run memory lifecycle (decay, prune, merge) | -| `smem_health` | Health diagnostics with actionable recommendations | +| `smem_consolidate` | Run the memory lifecycle (decay, prune, merge, dream) | | `smem_session` | Save/restore session state | -Plus 20 more for brain management, import/export, training, and diagnostics. +Plus 48 more for brain management, import/export, training, sync, visualisation, and diagnostics. All 56 are included in the open-source package — no license keys, no paywalls. + +### Pro Features, Free + +The bundled community plugin unlocks what upstream forks typically gate behind a paid tier: cone/HNSW vector search, smart merge, and directional compression are all included at no cost. ## Quick Start +### pip (Python 3.11+) + ```bash -pip install surreal-memory +pip install "surreal-memory[surrealdb]" ``` -### Claude Code (Plugin) +### Claude Code Plugin + ```bash /plugin marketplace add acidkill/surreal-memory ``` +### Docker (full stack with SurrealDB) + +```bash +docker compose -f docker-compose.surrealdb.yml up -d +``` + ### Manual MCP Config + ```json { "mcpServers": { "surreal-memory": { "command": "uvx", - "args": ["surreal-memory"] + "args": ["surreal-memory[surrealdb]"] } } } ``` +Works with Claude Code, Cursor, Windsurf, VS Code (Cline/Continue), Zed, and Gemini CLI. + ### Optional: Cross-Language Embeddings -Core recall works without embeddings. Enable for cross-language search: +Core recall works without any embedding API. Enable vector search for cross-language queries: ```toml # ~/.surrealmemory/config.toml [embedding] enabled = true -provider = "ollama" # or sentence_transformer, gemini, openai -model = "nomic-embed-text" +provider = "gemini" # or ollama, sentence_transformer, openai +model = "gemini-embedding-001" # 3072-dim; needs GEMINI_API_KEY ``` +The `auto` provider cascades at runtime: ollama → sentence-transformers → gemini → openai → openrouter, so it works offline-first. + +## The Backend: SurrealDB + +Surreal-Memory runs entirely on [SurrealDB](https://surrealdb.com/) — a multi-model engine that handles document storage, graph traversal, and HNSW vector search in a single database. There is no separate vector store, no SQLite file, and no external search service. The neuron/synapse graph is a native SurrealDB graph; vector embeddings live alongside it in the same engine. + +The brain is stored as a single portable export file (JSON) that can be versioned, snapshotted, and transplanted between installations. Multi-device sync uses Merkle-delta diffing over your own Cloudflare account — encrypted, no third-party cloud required. + +## Built on neural-memory + +Surreal-Memory is a fork of [nhadaututtheky/neural-memory](https://github.com/nhadaututtheky/neural-memory). It inherits the core neuron/synapse/fiber architecture, the spreading-activation retrieval model, and the MCP tool surface — credit goes upstream for that foundation. + +Three things differ in this fork: + +1. **SurrealDB backend** instead of SQLite. The multi-model engine enables native graph traversal and HNSW vector search without any additional infrastructure. +2. **All Pro-tier features unlocked for free** via the community plugin. Upstream gates cone/HNSW vector search, smart merge, and compression behind a paid Pro plan; this fork ships all of it open-source under MIT. +3. **Ongoing port** of storage-agnostic upstream improvements as they land, keeping the fork current. + +If you need a lightweight SQLite-backed version, the upstream project is the right choice. If you want the full feature set — graph + vector in one engine, all Pro features free — Surreal-Memory is for you. + ## Numbers -- **3,500+ tests**, 68% coverage -- **v2.29.0**, production-stable since v2.10 -- **14 memory types**, 24 synapse types, schema v22 -- **Python 3.11+**, async via aiosqlite -- **MIT license** -- **Dashboard**: FastAPI + React web UI for visualization +- **56 MCP tools** — 3-tool core, 53 fire automatically or on demand +- **5,500+ unit tests**, 67%+ CI coverage +- **15 memory types**: fact, decision, error, insight, preference, workflow, todo, and more +- **41 synapse types**: `CAUSED_BY`, `LEADS_TO`, `RESOLVED_BY`, `CONTRADICTS`, and 37 more +- **$0.00 per query** — no API keys needed for core encode + recall +- **Python 3.11+** · **MIT license** · SurrealDB backend +- **Dashboard**: FastAPI + React web UI for graph visualisation ## Links @@ -133,4 +172,4 @@ model = "nomic-embed-text" --- -*Surreal-Memory is open source and contributions are welcome. The spreading activation approach is particularly interesting if you've worked with cognitive architectures (ACT-R, Soar) — it's the same theoretical foundation applied to AI agent memory.* +*Surreal-Memory is open source and contributions are welcome. The spreading activation approach will feel familiar if you've worked with cognitive architectures like ACT-R or Soar — it's the same theoretical foundation applied to AI agent memory, now running on a multi-model graph database instead of flat files.* diff --git a/docs/promo/discord-anthropic.md b/docs/promo/discord-anthropic.md index 4c04f3ce..91ab2199 100755 --- a/docs/promo/discord-anthropic.md +++ b/docs/promo/discord-anthropic.md @@ -2,30 +2,32 @@ **Message:** -Hey! I built **Surreal-Memory** — an MCP server that gives Claude Code persistent memory across sessions. +Hey! I built **Surreal-Memory** — an MCP server that gives Claude Code (and other MCP clients) persistent, graph-based memory across sessions. -Instead of RAG/vector search, it uses **spreading activation on a neural graph** — memories are typed neurons connected by typed synapses (CAUSED_BY, LEADS_TO, RESOLVED_BY, etc.), and recall works by activating related concepts through the graph. +Instead of RAG/vector search, it uses **spreading activation on a neural graph** — memories are typed neurons connected by 41 typed synapse types (CAUSED_BY, LEADS_TO, RESOLVED_BY, CONTRADICTS, ...) and recall works by activating related concepts through the graph, not keyword matching. -**Quick setup:** +**Quick setup (Claude Code):** ``` /plugin marketplace add acidkill/surreal-memory ``` -Or manual: -```json -{ - "mcpServers": { - "surreal-memory": { - "command": "uvx", - "args": ["surreal-memory"] - } - } -} +Or pip + any MCP client: +```bash +pip install "surreal-memory[surrealdb]" +smem-mcp # starts the MCP server ``` -**Features:** 53 MCP tools, proactive auto-save, habits tracking, connection explainer, multi-brain, local SQLite, optional embeddings (Ollama/Gemini/OpenAI). +**What you get:** +- **56 MCP tools** — 3-tool core (remember / recall / health), the rest fire automatically +- **SurrealDB backend** — document + graph + vector HNSW in one database, no separate vector store +- **$0.00/query** — no LLM/embedding API calls for core encode + recall; no API keys required for core ops +- Memory lifecycle: Ebbinghaus decay, Hebbian reinforcement, sleep consolidation (ENRICH / PRUNE / MERGE / DREAM) +- All Pro-tier features free via the bundled community plugin (cone/HNSW vector search, smart merge, directional compression) — no license keys, no paywalls +- 15 memory types · single-file portable brain · JSON export/import · multi-device sync via your own Cloudflare account -**No API keys needed** for core recall — it's pure graph traversal. +**MIT · Python 3.11+ · 5,500+ unit tests** GitHub: https://github.com/acidkill/surreal-memory -Happy to answer any questions! +*Forked from nhadaututtheky/neural-memory — inherits the neuron/synapse/spreading-activation architecture; differs by swapping SQLite for SurrealDB and unlocking all Pro features free.* + +Happy to answer questions! diff --git a/docs/promo/hackernews.md b/docs/promo/hackernews.md index 0b1e2313..7599d17d 100755 --- a/docs/promo/hackernews.md +++ b/docs/promo/hackernews.md @@ -8,8 +8,12 @@ Surreal-Memory is an open-source MCP server that gives AI coding agents persistent memory using a neural graph with spreading activation retrieval — instead of the usual RAG/vector search approach. -Core idea: memories are stored as typed neurons connected by typed synapses (CAUSED_BY, LEADS_TO, RESOLVED_BY, etc.). Recall works by activating seed neurons and letting activation spread through the graph, naturally surfacing related memories through association. +Core idea: memories are stored as typed neurons connected by 41 typed synapses (CAUSED_BY, LEADS_TO, RESOLVED_BY, CONTRADICTS, etc.). Recall works by activating seed neurons and letting activation spread through the graph, naturally surfacing related memories through association — closer to how the brain retrieves context than cosine similarity over a flat embedding store. -No embedding API calls needed for core recall — it's pure algorithmic graph traversal. Embeddings are optional for cross-language search (supports Ollama, sentence-transformers, Gemini, OpenAI). +No embedding API calls needed for core recall — it's pure algorithmic graph traversal. Embeddings are optional for cross-language search (supports Ollama, sentence-transformers, Gemini, OpenAI). Core encode + recall costs $0.00 per query. -53 MCP tools (incl. cognitive reasoning layer), 5500+ tests, SQLite storage, Python 3.11+, MIT license. +Backed by SurrealDB's multi-model engine (document + graph + vector HNSW in one database — no separate vector store). 56 MCP tools, 5,500+ tests, 67%+ CI coverage, Python 3.11+, MIT. + +All Pro-tier features (HNSW vector search, smart merge, 5-tier compression, sleep consolidation) are free via the bundled community plugin — no license keys. + +This is a fork of nhadaututtheky/neural-memory. It inherits the neuron/synapse/fiber architecture and spreading-activation model; it differs in backend (SurrealDB instead of SQLite) and in unlocking all Pro features for free. diff --git a/docs/promo/reddit-claudeai.md b/docs/promo/reddit-claudeai.md index a0529deb..a46233f8 100755 --- a/docs/promo/reddit-claudeai.md +++ b/docs/promo/reddit-claudeai.md @@ -1,10 +1,10 @@ # Reddit r/ClaudeAI Post -**Title:** I built a persistent memory system for Claude Code that works like a brain — Surreal-Memory (open source, 53 MCP tools) +**Title:** I built a persistent memory system for Claude Code that works like a brain — Surreal-Memory (open source, 56 MCP tools, $0/query) **Body:** -Claude Code forgets everything between sessions. I got tired of re-explaining project context every time, so I built Surreal-Memory — an MCP server that gives Claude a persistent, associative memory. +Claude Code forgets everything between sessions. I got tired of re-explaining project context every time, so I built Surreal-Memory — an MCP server that gives Claude a persistent, associative memory backed by SurrealDB. ## How it's different from other memory tools @@ -12,50 +12,54 @@ Most memory MCP servers use RAG (embed text → vector search → return chunks) When you remember "Alice", it doesn't just find text containing "Alice". It activates the Alice neuron, which spreads to connected concepts: the meeting where you discussed rate limiting → the outage it caused → the JWT decision that led to it. You get the full causal chain, not just keyword matches. -**No LLM/embedding API required for core recall.** It's pure algorithmic graph traversal. Embeddings are optional for cross-language search. +**No LLM or embedding API required for core encode and recall.** It's pure algorithmic graph traversal. No API keys needed for core operations. Embeddings (Ollama, Gemini, OpenAI, sentence-transformers) are optional and used for cross-language search only. ## What it does -- **53 MCP tools**: `smem_remember`, `smem_recall`, `smem_context`, `smem_explain`, `smem_habits`, and more +- **56 MCP tools**: 3-tool core (`smem_remember`, `smem_recall`, `smem_health`) — the other 53 fire automatically - **Spreading activation retrieval**: memories surface through association, not search -- **Connection explainer**: ask "how are X and Y connected?" and get the exact path through the knowledge graph -- **Habits tracking**: detects recurring patterns in your workflow -- **Multi-brain**: separate memory spaces for different projects -- **Proactive auto-save**: captures memories during session + saves summary on exit -- **Local-first**: SQLite, zero external deps, fully offline +- **41 synapse types** (`CAUSED_BY`, `LEADS_TO`, `CONTRADICTS`, `RESOLVED_BY`) — causal reasoning, not just similarity +- **15 memory types**: fact, decision, error, insight, preference, workflow, todo, and more +- **Memory lifecycle**: Ebbinghaus decay, Hebbian reinforcement, sleep consolidation (ENRICH / PRUNE / MERGE / DREAM), 5-tier compression +- **ALL Pro features free**: cone/HNSW vector search, smart merge, directional compression — no license keys, no paywalls +- **Multi-device sync** via your own Cloudflare account (Merkle delta, encrypted) +- **Single portable brain**: export / import JSON, versioning, brain transplant + +## Backend + +SurrealDB multi-model engine — document + graph + vector HNSW in **one** database. No separate vector store, no SQLite, no extra infrastructure. Spin it up with: + +```bash +docker compose -f docker-compose.surrealdb.yml up -d +``` ## Quick start ```bash -pip install surreal-memory +pip install "surreal-memory[surrealdb]" ``` Add to Claude Code: + ```bash /plugin marketplace add acidkill/surreal-memory ``` -Or configure MCP manually: -```json -{ - "mcpServers": { - "surreal-memory": { - "command": "uvx", - "args": ["surreal-memory"] - } - } -} -``` +Works with Claude Code, Cursor, Windsurf, VS Code, Cline, Zed, and Gemini CLI. ## Numbers -- 3,500+ tests, 68% coverage -- v2.29.0, production-stable -- 14 memory types, 24 synapse types -- Python 3.11+, async, MIT license -- Optional embeddings: Ollama, Gemini (free), OpenAI, sentence-transformers +- **56 MCP tools** · **5,500+ unit tests** · **67%+ CI coverage** +- **$0.00/query** — no API calls for core encode + recall +- 15 memory types · 41 synapse types +- Python 3.11+ · async · MIT license + +## Relationship to neural-memory + +Surreal-Memory is a fork of [nhadaututtheky/neural-memory](https://github.com/nhadaututtheky/neural-memory). It inherits the neuron/synapse/fiber architecture, spreading activation, and the MCP tool surface — credit where it's due. The key differences: (1) SurrealDB multi-model backend replaces SQLite; (2) ALL Pro-tier features (vector search, smart merge, compression) are unlocked free via the community plugin — upstream gates these behind a paid license; (3) ongoing port of storage-agnostic upstream improvements. + +--- GitHub: https://github.com/acidkill/surreal-memory -Docs: https://acidkill.github.io/surreal-memory/ Happy to answer questions about the architecture or how spreading activation works in practice. diff --git a/docs/promo/reddit-localllama.md b/docs/promo/reddit-localllama.md index 54653aea..8c1fbbae 100755 --- a/docs/promo/reddit-localllama.md +++ b/docs/promo/reddit-localllama.md @@ -1,63 +1,63 @@ # Reddit r/LocalLLaMA Post -**Title:** Open-source graph-based memory for AI coding agents — spreading activation instead of RAG (no API keys needed) +**Title:** Open-source graph memory for AI agents — spreading activation instead of RAG, $0/query, no API keys needed **Body:** -I've been working on an alternative approach to giving AI agents persistent memory. Instead of the usual RAG pipeline (embed → vector search → return chunks), I built a system that stores memories as a neural graph and retrieves them through **spreading activation**. +I've been working on an alternative approach to persistent memory for AI agents. Instead of the usual RAG pipeline (embed → vector search → return chunks), it stores memories as a neural graph and retrieves them through **spreading activation** — closer to how biological memory works than cosine similarity. ## The problem with RAG for agent memory -RAG treats memory as a search problem: "find text similar to this query." It works, but it loses structure. When you ask "why did the outage happen?", RAG returns "JWT caused the outage" — but not *why* you chose JWT, who suggested it, or what it replaced. +RAG treats memory as a search problem: "find text similar to this query." It works for documents, but it loses causal structure. When you ask "why did the outage happen?", RAG returns "JWT caused the outage" — but not *why* JWT was chosen, who suggested it, or what decision it replaced. ## Spreading activation approach -Surreal-Memory stores everything as typed neurons connected by typed synapses (`CAUSED_BY`, `LEADS_TO`, `SUGGESTED_BY`, `RESOLVED_BY`, etc.). Recall works by: +[Surreal-Memory](https://github.com/acidkill/surreal-memory) stores everything as typed neurons connected by 41 explicit synapse types (`CAUSED_BY`, `LEADS_TO`, `SUGGESTED_BY`, `RESOLVED_BY`, `CONTRADICTS`, ...). Recall works by: 1. Activate seed neurons matching your query 2. Activation spreads through synapses (weighted, with decay) -3. Most-activated neurons form the response context +3. Most-activated neurons surface as context -This gives you multi-hop reasoning for free. "Why did the outage happen?" traces: `outage ← CAUSED_BY ← JWT ← SUGGESTED_BY ← Alice ← DECIDED_AT ← Tuesday meeting`. +This gives you multi-hop causal reasoning. "Why did the outage happen?" traces: `outage ← CAUSED_BY ← JWT ← SUGGESTED_BY ← Alice ← DECIDED_AT ← Tuesday meeting`. -**No embedding API calls needed.** Core recall is pure graph traversal with O(n) complexity on the local subgraph. Embeddings are optional (supports Ollama, sentence-transformers, Gemini free tier, OpenAI). +**No embedding API calls required for core recall.** It's graph traversal. Embeddings are optional and local-first (Ollama, sentence-transformers, or nothing at all). ## Technical details -- **Storage**: SQLite via aiosqlite (async), FTS5 for text search -- **Graph**: 14 neuron types, 24 synapse types, fiber bundles for episodic grouping +- **Storage**: SurrealDB multi-model backend (document + graph + vector HNSW in one DB — no separate vector store) +- **Graph**: 15 memory types (fact, decision, error, insight, preference, workflow, todo, ...), 41 synapse types, fiber bundles for episodic grouping - **Retrieval**: Spreading activation with configurable decay, threshold, and max hops -- **Consolidation**: Memory lifecycle — decay, reinforcement, pruning of orphan nodes -- **Extraction**: Entity/keyword/temporal extraction, Vietnamese NLP support -- **MCP server**: 53 tools (incl. cognitive reasoning), stdio + HTTP transport, works with Claude Code, Cursor, etc. -- **Tests**: 3,976+, 67% coverage, CI with mypy + ruff + pytest +- **Lifecycle**: Ebbinghaus decay, Hebbian reinforcement, sleep consolidation (ENRICH/PRUNE/MERGE/DREAM), 5-tier compression +- **MCP server**: 56 tools (3-tool core: smem_remember, smem_recall, smem_health), stdio + HTTP, works with Claude Code, Cursor, Windsurf, Cline, Zed, Gemini CLI +- **Pro features**: cone/HNSW vector search, smart merge, directional compression — all FREE via the bundled community plugin, no license keys +- **Tests**: 5,500+ unit tests, 67%+ CI coverage, mypy + ruff + pytest -## What makes it interesting for local LLM users +## Why local/offline users care -- **Zero API cost**: core recall doesn't need embeddings or LLM calls -- **Ollama integration**: if you want embeddings, use your local Ollama instance -- **Works with any MCP client**: not locked to Claude — any agent that speaks MCP -- **Light**: single SQLite file, ~23MB for 1000+ memories with full graph +- **$0.00/query**: core encode and recall make zero LLM or embedding API calls — works fully offline +- **No API keys needed** for core operations +- **Ollama support**: opt-in local embeddings if you want semantic similarity on top of graph traversal +- **Single portable brain**: export/import JSON, brain versioning and transplant, multi-device sync via your own Cloudflare account (Merkle delta, encrypted) +- **MIT licensed**: no paywalls, no telemetry, no vendor lock-in + +## Relationship to neural-memory + +Surreal-Memory is a fork of [nhadaututtheky/neural-memory](https://github.com/nhadaututtheky/neural-memory). It inherits the neuron/synapse/fiber architecture, spreading activation model, and the MCP tool surface from upstream (credit where it's due). The main differences: SurrealDB multi-model backend instead of SQLite; all Pro-tier features (vector search, smart merge, compression) unlocked free via the community plugin — upstream gates these behind a paid plan; and ongoing port of storage-agnostic upstream improvements. ## Install ```bash -pip install surreal-memory +# Core install +pip install "surreal-memory[surrealdb]" -# With local embeddings via Ollama -pip install surreal-memory[embeddings] -``` +# Claude Code plugin +# /plugin marketplace add acidkill/surreal-memory -Config for Ollama embeddings: -```toml -# ~/.surrealmemory/config.toml -[embedding] -enabled = true -provider = "ollama" -model = "nomic-embed-text" +# Docker (recommended for persistent brain) +docker compose -f docker-compose.surrealdb.yml up -d ``` GitHub: https://github.com/acidkill/surreal-memory -Architecture docs: https://acidkill.github.io/surreal-memory/ +Docs: https://acidkill.github.io/surreal-memory/ -The codebase is MIT licensed. Contributions welcome. +MIT licensed. Early project — contributions welcome. diff --git a/docs/promo/vs-neural-memory.md b/docs/promo/vs-neural-memory.md new file mode 100644 index 00000000..46b45753 --- /dev/null +++ b/docs/promo/vs-neural-memory.md @@ -0,0 +1,51 @@ +# Surreal-Memory vs neural-memory + +## A Fair Introduction + +Surreal-Memory is a fork of [nhadaututtheky/neural-memory](https://github.com/nhadaututtheky/neural-memory). The neuron/synapse/fiber architecture, spreading-activation retrieval, and the MCP tool surface all originate upstream — that work deserves full credit. + +This page explains what was inherited and what changed so you can make an informed choice between the two. + +--- + +## What We Inherited + +- Neurons, typed synapses, and the fiber graph model +- Spreading-activation recall (biological propagation model, not keyword/vector RAG) +- 41 explicit synapse types (`CAUSED_BY`, `LEADS_TO`, `RESOLVED_BY`, `CONTRADICTS`, …) for causal reasoning +- 15 memory types (`fact`, `decision`, `error`, `insight`, `preference`, `workflow`, `todo`, …) +- Memory lifecycle: decay (Ebbinghaus curve), Hebbian reinforcement, sleep-consolidation phases +- The 56-tool MCP surface — including the 3-tool core (`smem_remember`, `smem_recall`, `smem_health`) + +--- + +## What We Changed + +- **Storage backend replaced:** SurrealDB multi-model engine (document + graph + vector HNSW in one DB) instead of SQLite. No separate vector store, no `aiosqlite` dependency. +- **All Pro features unlocked — free.** Upstream gates cone/HNSW vector search, smart merge, and directional compression behind a paid Pro tier. In Surreal-Memory these ship as the bundled community plugin: no license key, no paywall, no tiers. +- **$0.00 per query for core ops.** No LLM or embedding API calls are required for core encode + recall. The system works offline (no API keys needed for core operations). +- **Active upstream port.** Storage-agnostic improvements from the upstream repo are ported on an ongoing basis as they reach a stable state. + +--- + +## Side-by-Side Comparison + +| Feature | neural-memory (upstream) | Surreal-Memory (fork) | +|---|---|---| +| **Storage backend** | SQLite / aiosqlite | SurrealDB (document + graph + vector) | +| **Vector search** | Pro tier only | Free — bundled community plugin (HNSW) | +| **Semantic recall** | Spreading activation | Spreading activation (inherited) | +| **Smart consolidation** | Pro tier only | Free — bundled community plugin | +| **Directional compression** | Pro tier only | Free — bundled community plugin | +| **License / pricing** | MIT; Pro features paywalled | MIT; all features free | +| **Multi-model DB** | No (single SQLite file) | Yes — SurrealDB (doc + graph + vector) | + +--- + +## Acknowledgment + +Surreal-Memory would not exist without the architecture, tooling, and ideas built by [@nhadaututtheky](https://github.com/nhadaututtheky). Thank you for open-sourcing neural-memory under MIT. + +--- + +*Repo: [github.com/acidkill/surreal-memory](https://github.com/acidkill/surreal-memory) · PyPI: `surreal-memory` · CLI: `smem` · MIT · Python 3.11+* diff --git a/integrations/surreal-memory-client/package-lock.json b/integrations/surreal-memory-client/package-lock.json index 4e0dcc8c..638e23c4 100644 --- a/integrations/surreal-memory-client/package-lock.json +++ b/integrations/surreal-memory-client/package-lock.json @@ -1,12 +1,12 @@ { "name": "@acidkill/surreal-memory-client", - "version": "2.4.0", + "version": "2.5.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@acidkill/surreal-memory-client", - "version": "2.4.0", + "version": "2.5.0", "license": "MIT", "devDependencies": { "@types/node": "^20.0.0", diff --git a/integrations/surreal-memory-client/package.json b/integrations/surreal-memory-client/package.json index 06d77feb..0b7bbee6 100644 --- a/integrations/surreal-memory-client/package.json +++ b/integrations/surreal-memory-client/package.json @@ -1,6 +1,6 @@ { "name": "@acidkill/surreal-memory-client", - "version": "2.4.0", + "version": "2.5.0", "description": "TypeScript client for the Surreal-Memory REST API — typed access to brains, neurons, synapses, fibers, recall, and sync.", "type": "module", "main": "dist/index.cjs", diff --git a/integrations/surrealmemory/package-lock.json b/integrations/surrealmemory/package-lock.json index a8aa2226..e297d0f1 100755 --- a/integrations/surrealmemory/package-lock.json +++ b/integrations/surrealmemory/package-lock.json @@ -1,12 +1,12 @@ { "name": "@surrealmemory/openclaw-plugin", - "version": "2.4.0", + "version": "2.5.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@surrealmemory/openclaw-plugin", - "version": "2.4.0", + "version": "2.5.0", "license": "MIT", "devDependencies": { "@types/node": "^25.2.2", diff --git a/integrations/surrealmemory/package.json b/integrations/surrealmemory/package.json index 8f33f591..643a5c49 100755 --- a/integrations/surrealmemory/package.json +++ b/integrations/surrealmemory/package.json @@ -1,6 +1,6 @@ { "name": "surrealmemory", - "version": "2.4.0", + "version": "2.5.0", "description": "Surreal-Memory plugin for OpenClaw — graph-based persistent memory for AI agents with SurrealDB backend", "type": "module", "main": "dist/index.js", diff --git a/pyproject.toml b/pyproject.toml index f3ccbda1..0cfd7989 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "surreal-memory" -version = "2.4.0" +version = "2.5.0" description = "Reflex-based memory system for AI agents with SurrealDB backend — retrieval through activation, not search" readme = "README.md" license = "MIT" diff --git a/src/surreal_memory/__init__.py b/src/surreal_memory/__init__.py index 30450465..43051d0c 100755 --- a/src/surreal_memory/__init__.py +++ b/src/surreal_memory/__init__.py @@ -16,7 +16,7 @@ from surreal_memory.engine.reflex_activation import CoActivation, ReflexActivation from surreal_memory.engine.retrieval import DepthLevel, ReflexPipeline, RetrievalResult -__version__ = "2.4.0" +__version__ = "2.5.0" __all__ = [ "__version__", diff --git a/tests/unit/test_health_fixes.py b/tests/unit/test_health_fixes.py index 2a195c35..a8c53ba4 100755 --- a/tests/unit/test_health_fixes.py +++ b/tests/unit/test_health_fixes.py @@ -485,7 +485,7 @@ class TestVersionBump: def test_version_is_current(self) -> None: import surreal_memory - assert surreal_memory.__version__ == "2.4.0" + assert surreal_memory.__version__ == "2.5.0" class TestPackageIntegrity: diff --git a/vscode-extension/package-lock.json b/vscode-extension/package-lock.json index 876d1251..cad428f0 100755 --- a/vscode-extension/package-lock.json +++ b/vscode-extension/package-lock.json @@ -1,12 +1,12 @@ { "name": "surrealmemory", - "version": "2.4.0", + "version": "2.5.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "surrealmemory", - "version": "2.4.0", + "version": "2.5.0", "license": "MIT", "dependencies": { "cytoscape": "^3.33.1", diff --git a/vscode-extension/package.json b/vscode-extension/package.json index 8e3dc7e7..c14d066c 100755 --- a/vscode-extension/package.json +++ b/vscode-extension/package.json @@ -2,7 +2,7 @@ "name": "surrealmemory", "displayName": "Surreal-Memory", "description": "Visual brain explorer, inline recall, and memory management for Surreal-Memory", - "version": "2.4.0", + "version": "2.5.0", "publisher": "ai-flow-nowak", "license": "MIT", "preview": true,