crowmemory

KO | EN

gitlite — search

#ai-agents #graphql #automation #deep-learning #html #pytorch #java #agents #claude-code #shell

(★ 9)

Crow Memory - External synaptic memory for AI coding agents. Stores your coding style, bug intuition, and architectural preferences as compressed weight matrices.

File Explorer

ZIP Download

- FUNDING.yml
- tasks.json
- - 000700_code-batch-d-report.md
  - 091200_code-batch-e-report.md
  - 091600_debug-review-report.md
  - 092640_code-p5-fix-report.md
  - 093000_code-quality-gate-report.md
  - 093300_ask-final-audit-report.md
  - 154200_code-merge-value-bank-report.md
  - 162300_code-purge-debris-report.md
  - 163640_code-docs-audit-report.md
  - 171820_code-myk1yt-cleanup-report.md
  - 233400_architect-report.md
  - 234100_code-report.md
  - 234700_code-batch-b-report.md
  - 235500_code-batch-c-report.md
  - decisions.md
  - requirement-checklist.md
- CROW_MEMORY_AUTOSTART_DESIGN.md
- PROJECT_CONTEXT.md
- bg.json
- bn.json
- cs.json
- da.json
- de.json
- el.json
- en.json
- es.json
- et.json
- fi.json
- fr.json
- hi.json
- hr.json
- hu.json
- id.json
- it.json
- ja.json
- ko.json
- lt.json
- lv.json
- ms.json
- nb.json
- nl.json
- pl.json
- pt-br.json
- ro.json
- ru.json
- sk.json
- sl.json
- sv.json
- th.json
- tr.json
- uk.json
- vi.json
- zh-cn.json
- zh-tw.json
- crowww600x600.png
- Gemini_Generated_Image_8hjlaz8hjlaz8hjl.png
- e2e_verify_server.py
- final_verify.py
- ingest_session_result.py
- merge_value_bank.py
- migrate_value_bank.py
- probe_endpoints.py
- probe_mcp_handshake.py
- purge_search_debris.py
- register_crow_task.ps1
- run_elevated.bat
- test_routes.py
- verify_mcp_migration.py
- en.md
- ko.md
- test_merge.py
- test_migrate.py
- test_purge_debris.py
- test_recall_precision.py
- test_sanitize.py
- test_tool_schema.py
.gitignore
AGENTS.md
backup_manager.py
CHANGELOG.md
crow_core.py
crow_i18n.py
crow_mcp_server.py
CROW_MEMORY_ARCHITECTURE.md
crow_sanitize.py
custom_modes.example.yaml
hitl_panel.html
install.ps1
install.py
LICENSE
README.md
requirements.txt
start_crow_sse.bat
system_prompt.example.md
test.bat
watch_crow_sse.bat

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

## Developer's Note / Philosophy

### 1. Why the Name "Crow"?
Crows use tools, recognize faces, possess long-term memory, and have the "situational awareness" to adapt to circumstances. "Crow Memory" was built upon this philosophy.

### 2. Why This Technology?
Transformer-based LLMs are frozen at training time — they cannot remember their users. Solutions based on RAG or SQLite accumulate information indefinitely and deliver 100% accurate recall like "notes in a notepad," but that is precisely the problem: it's a "jot it down and look it up later" approach. The human and animal brain doesn't work that way. Old habits fade, new patterns strengthen.

Forgetting is not a bug. Crow's fixed-size weight matrices and λ (decay rate) implement this "creative forgetting." By sacrificing 100% accurate recall, an AI that remembers through Crow responds with biases closer to your *present* self. The goal is low-latency, real-time synaptic plasticity — something that feels alive.

### 3. Who Is This For?
- **Anyone** who wants an AI that remembers their habits and adapts to them
- **Vibe coders** — those who want their AI to feel like a "colleague who knows them well"
- **Multi-agent users** — those who switch between multiple AI agents yet share a single `crow.bin` to maintain a consistent "AI that knows you"
- **Local-first advocates** — those who don't want to hand their personal data over to a cloud API

*"If you share this philosophy and want to join me on this journey, you are always welcome."*

---
[![Gumroad Sponsor](https://img.shields.io/badge/Gumroad-Sponsor-FF90A0?style=for-the-badge&logo=gumroad&logoColor=white)](https://teamsunplaza.gumroad.com/l/crowmemory)

> *"Crow remembers not the code, but the hand that wrote it."*

**Crow** is an external synaptic memory system for LLM-powered AI assistants. It plugs into any MCP-compatible coding agent (Claude, GPT, DeepSeek, Gemini, etc.) and stores your coding style, bug intuition, architectural preferences, and personal context as compressed weight matrices inside a fixed-size `crow.bin` file. Think of it as long-term muscle memory for your AI pair programmer.

---

## Quick Start

### 1. Requirements

- **Python 3.10+**
- **Zoo Code** (or any MCP-compatible AI coding agent)
- Git (to clone the repository)

### 2. Install (One Command)

**Windows (PowerShell):**
```powershell
git clone https://github.com/myk1yt/crowmemory.git
cd crowmemory
.\install.ps1
```

**macOS / Linux:**
```bash
git clone https://github.com/myk1yt/crowmemory.git
cd crowmemory
python install.py
```

The installer automatically:
- Installs Python dependencies
- Initializes `crow.bin` (140MB fixed-size weight matrix)
- Registers `CrowMemoryAuto` in Windows Task Scheduler — **auto-starts the SSE server at user logon** (no manual commands needed)
- Creates an **"Orchestrator + Crow"** custom mode with `allowedMcpServers` + AUTO-INGEST (Crow Memory integrated into the Orchestrator workflow)
- Configures Crow Memory via **global MCP settings** (no project-level `.roo/mcp.json` needed)
- Registers a Startup `.bat` so the SSE server also starts with Windows
- Pre-authorizes all 3 Crow tools (`alwaysAllow`)

> ⚡ **That's it.** No manual server commands. The SSE server auto-starts when you log into Windows and **survives IDE restarts** (runs as a detached background process).

### How Auto-Start Works (v1.5.0)

The installer registers a Windows Task Scheduler task (`CrowMemoryAuto`) that launches the server at user logon:

1. **User logs into Windows** → Task Scheduler triggers `CrowMemoryAuto` (30s delay)
2. [`start_crow_sse.bat`](start_crow_sse.bat) launches the server as a detached process
3. Server begins listening on `127.0.0.1:9020` (SSE) + `127.0.0.1:9021` (Streamable HTTP)
4. Health check confirms readiness (max ~55s)
5. **Open VS Code** → Zoo Code / Kimi Code / Roo Code detects the running server via Global MCP config → Crow activates immediately

**Reliability**: If the server fails to start, Task Scheduler automatically retries every 3 minutes (up to 3 times). As a fallback, the installer also places a delayed launcher in the Windows Startup folder.

### 3. Restart & Switch Mode

1. **Restart Zoo Code**
2. Open the `crowsmemory` workspace folder
3. Switch mode to **"Orchestrator + Crow"** — for task-delegation workflows with Crow Memory integration
4. Done. The SSE server auto-starts. Crow activates on every response.

### 4. Verify

Ask the AI:
> "Call crow_admin with action=\"diagnostics\" to check Crow memory status."

If Crow is alive, it will report register norms, update count, and value bank size.

### How Auto-Activation Works

Two layers ensure Crow is always active:

| Layer | Mechanism |
|-------|-----------|
| **SSE Auto-Start** | Windows Task Scheduler (`CrowMemoryAuto`) with `AtLogon` trigger |
| **UNIVERSAL RECALL + AUTO-INGEST** | Custom mode system prompt (`custom_modes.yaml` for Zoo Code) |

The installer copies [`system_prompt.example.md`](system_prompt.example.md) → `memory/system_prompt.md` with 3 pre-evolved rules.

---

## `.zoo/` Configuration Structure

Crow Memory now supports the Zoo Code `.zoo/` configuration convention:

| File | Description |
|------|-------------|
| [`.zoo/config.json`](.zoo/config.json) | Project-level Zoo configuration — default mode, version, Crow auto-recall/ingest flags |
| [`.zoo/config.schema.json`](.zoo/config.schema.json) | JSON Schema for `.zoo/config.json` validation |
| [`.roo/mcp.schema.json`](.roo/mcp.schema.json) | JSON Schema for `.roo/mcp.json` MCP configuration validation |

### Default Mode

Set `"defaultMode": "orchestrator-crow"` in [`.zoo/config.json`](.zoo/config.json) to automatically activate the Orchestrator + Crow mode when you open the project.

### Templates

The [`templates/`](templates/) directory contains reusable configuration templates:

| Template | Description |
|----------|-------------|
| [`templates/zoo-config.json`](templates/zoo-config.json) | Template for `.zoo/config.json` with Crow Memory defaults |
| [`templates/.roo/mcp.json`](templates/.roo/mcp.json) | Template for `.roo/mcp.json` with Crow Memory MCP server config |

---

## How It Works

```
User query → LLM (via MCP over SSE)
                ↓ crow_recall("query", domain="all", project="my-app")
           Crow MCP Server (SSE 9020 / HTTP 9021)
                ↓ encode() (sha256-cached) → Sᵀ @ q → confidence
                ↓ value_bank nearest-neighbor (FAISS) + effective-sim ranking
                ↓ scrub gate + similarity cutoff (0.35; cross-project 0.42)
                ↓ same-project boost ×1.05 (capped ×1.15)
           crow.bin (8-register weight matrix + tagged value_bank)
                ↓
           [User Bias] hints returned → injected into context
                ↓
           LLM generates response aligned with your preferences

Multi-client safe: One dual-mode server → many AI clients share one crow.bin
```

### The 8 Registers (Hybrid: Code + Life)

**Code Domain**

| Register | Dimensions | λ (EMA decay) | Capacity | Domain |
|----------|-----------|----------------|----------|--------|
| `style` | 4096×4096 | 0.9999 (~7K to halve) | ~2,000 patterns | Variable naming, comment style, folder aesthetics |
| `bug` | 2048×2048 | 0.9995 (~1.4K to halve) | ~800 patterns | Abstract bug families, not exact fixes |
| `arch` | 2048×2048 | 0.9995 | ~800 patterns | Early-return vs deep-nesting, error-handling philosophy |
| `context` | 2048×4096 | 0.9500 (~14 to halve) | ~400 patterns | Recent project context, active file context |

**Life Domain** (NEW)

| Register | Dimensions | λ (EMA decay) | Capacity | Domain |
|----------|-----------|----------------|----------|--------|
| `life_pref` | 4096×4096 | 0.9999 | ~2,000 | Personal taste, preferred environments, habits |
| `life_avoid` | 2048×2048 | 0.9995 | ~800 | Situations to avoid, dislikes, past mistakes |
| `life_phil` | 2048×2048 | 0.9995 | ~800 | Life philosophy, decision principles, values |
| `life_context` | 2048×4096 | 0.9500 | ~400 | Current plans, recent events, ongoing concerns |

> **Backward compatible**: `style`, `bug`, `arch`, `context` still work as before.

### How Crow Remembers (Without Being Asked)

The core challenge: LLMs don't spontaneously call tools. Crow solves this with four layers:

| Layer | Mechanism | When |
|-------|-----------|------|
| **AUTO-INGEST** | AI proactively evaluates every exchange and calls `crow_ingest` when it detects preferences, philosophy, corrections, or context. No "remember this" needed. | Every exchange |
| **MCP Prompt** | `crow_memory_bias` is auto-loaded by the LLM host at session start. No tool call needed. | Every session |
| **Auto-Inject** | Custom mode system prompt pre-generates a `[User Bias]` block for manual injection. | Pre-task hook |
| **Evolved Rules** | Statistically significant patterns promoted to `system_prompt.md` via HITL approval. | Permanent |

---

## 3 MCP Tools + 2 Prompts (v1.5.0 — AD-5 Tool Consolidation)

The former 10-tool surface was consolidated into **3 tools**. Legacy capabilities are absorbed as parameters/actions — no functionality was lost.

### MCP Tools (auto-connected via Zoo Code)

| Tool | Description |
|------|-------------|
| `crow_recall` | Retrieve context from memory. Parameters: `query` (required), `register` (single register or `all`), `domain` (`code`/`life`/`all`), `top_k` (1–5), `format` (`hint` JSON — default, or `bias_block` for the `[User Bias]` system-prompt block), `project` / `strict_project` (project-scoped recall) |
| `crow_ingest` | Store new experiences into synaptic memory. Parameters: `key`, `value`, `register` (required); `polarity` optional — omit it and pass `exit_code` for automatic build-result polarity mapping (+1.5/+0.5 on success, −0.5/−1.0 on failure, adjusted by `user_edited`). Content is sanitized first — pure-noise input is rejected without touching memory. |
| `crow_admin` | Administrative operations via `action` + `args` dispatch: `diagnostics` (memory health/statistics), `drift` (consistency check), `prompt` (read/append/stats on `system_prompt.md`), `backup` (create/rotate/list/recover), `evolve` (propose system prompt improvements), `project_info` (list/create project-tagged instances) |

> **Project tagging**: `crow_recall` and `crow_ingest` accept an optional `project` tag. Entries tagged with a project get a same-project similarity boost at recall time; untagged (`null`) entries stay global. `strict_project` hard-filters cross-project entries out.

> **Input sanitization**: All ingested content passes through [`crow_sanitize.py`](crow_sanitize.py) (`scrub_text`) — kaomoji, emoji, and Korean jamo-run noise are removed while C++ code, URLs, identifiers, and Korean text are protected.

### Maintenance Scripts (dry-run first)

| Script | Description |
|--------|-------------|
| [`scripts/migrate_value_bank.py`](scripts/migrate_value_bank.py) | Migrate legacy value_bank entries (sanitize + add `project` field). Runs in **dry-run** by default; pass `--apply` to write. |
| [`scripts/merge_value_bank.py`](scripts/merge_value_bank.py) | Merge value_bank files (dedupe, resolve conflicts). Dry-run by default; `--apply` to write. |
| [`scripts/purge_search_debris.py`](scripts/purge_search_debris.py) | Remove search-log debris entries from value_bank. Dry-run by default; `--apply` to write. |

### MCP Prompts (Auto-Loaded by Host)

| Prompt | Description |
|--------|-------------|
| `crow_memory_bias` | Full context: evolved rules + recent memory hints. Loaded automatically at session start. |
| `crow_evolved_rules` | Permanent rules from `system_prompt.md`. |

### Fork Files (`-myk1yt`) Consolidation & Data Layout

All `-myk1yt` file copies (docs, code, bats, requirements) have been **fully merged into the canonical originals and removed** — the canonical files are the single source of truth. Only the historical **memory data archive** remains:

| File | Status |
|------|--------|
| `memory/crow.bin` + `memory/value_bank.json` | ✅ **Active** |
| `memory/crow-myk1yt.bin` / `value_bank-myk1yt.json` / `recall_stats-myk1yt.json` | 🗄️ Historical archive (not read by the server, preserved untouched) |

> The `CROW_STATE_TAG` mechanism ([`crow_mcp_server.py`](crow_mcp_server.py) `resolve_state_path()`) can still create isolated instances (`crow-<tag>.bin`) when intentionally set — no tag is currently in use.

### Tests

**231 tests** across 6 suites: `test_sanitize` (55), `test_tool_schema` (56), `test_recall_precision` (42), `test_merge` (33), `test_migrate` (27), `test_purge_debris` (18) — under [`tests/`](tests/).

---

## Internationalization (i18n) — 36 Languages

Crow Memory automatically detects your VS Code language setting and displays all messages, MCP tool descriptions, and installer output in your preferred language.

**Supported locales:**
🇺🇸 English · 🇰🇷 한국어 · 🇯🇵 日本語 · 🇨🇳 简体中文 · 🇹🇼 繁體中文 · 🇫🇷 Français · 🇩🇪 Deutsch · 🇮🇹 Italiano · 🇪🇸 Español · 🇧🇷 Português · 🇷🇺 Русский ... and 26 more.

The installer, MCP server, and system prompt templates all use your VS Code locale automatically. If a translation is missing, English is used as fallback.

---

## Sharing Policy (Important!)

| File | Share? | Reason |
|------|--------|--------|
| `crow_core.py` | ✅ Yes | Core engine (code) |
| `crow_sanitize.py` | ✅ Yes | Input noise sanitizer (kaomoji/emoji/jamo-run scrubbing) |
| `crow_mcp_server.py` | ✅ Yes | MCP server |
| `backup_manager.py` | ✅ Yes | Backup utility |
| `hitl_panel.html` | ✅ Yes | HITL UI |
| `crow_i18n.py` | ✅ Yes | i18n core module |
| `i18n/*.json` | ✅ Yes | Translation files (36 languages) |
| `system_prompt.example/` | ✅ Yes | Locale-specific prompt templates |
| `requirements.txt` | ✅ Yes | Dependencies |
| **`memory/crow.bin`** | ❌ **No** | Your personal synaptic memories |
| **`memory/value_bank.json`** | ❌ **No** | Your experience data |
| **`memory/recall_stats.json`** | ❌ **No** | Your recall statistics |
| `system_prompt.example.md` | ✅ Yes | Evolved rules template (copied to memory/ on install) |
| `install.py` / `install.ps1` | ✅ Yes | One-command installers |
| **`memory/system_prompt.md`** | ❌ **No** | Your evolved rules (auto-copied from template) |

The included `.gitignore` automatically excludes all personal memory files.

---

## Multi-Client Setup (Zoo Code + others)

### ✅ Default: Dual-Mode Server (Auto-Start)

The installer configures a **dual-mode** server (SSE + Streamable HTTP) by default. This is the only safe way to share `crow.bin` across multiple AI clients:

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Zoo Code    │     │  Kimi Code   │     │  Other Client│
│  (SSE MCP)   │     │  (HTTP MCP)  │     │  (SSE MCP)   │
└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
       │                    │                    │
       └────────┬───────────┴───────────┬────────┘
                │                       │
     http://127.0.0.1:9020/sse   http://127.0.0.1:9021/
       ┌────────┴───────────────────────┴────────┐
       │          Crow MCP Server                │
       │  (Dual Mode: SSE port 9020 +            │
       │   Streamable HTTP port 9021)            │
       │  Auto-started by Windows Task Scheduler (AtLogon)     │
       └────────┬───────────────────────┬────────┘
                │                       │
       ┌────────┴───────────────────────┴────────┐
       │              crow.bin                   │
       │           (single source)               │
       └─────────────────────────────────────────┘
```

**How it works:**
1. You open the `crowsmemory` workspace in **any** VS Code-based editor
2. [`.vscode/tasks.json`](.vscode/tasks.json) auto-runs [`start_crow_sse.bat`](start_crow_sse.bat) — if server is already running (detached from previous session), exits instantly; otherwise starts it detached + polls until ready
3. The server starts in **dual mode**: SSE on port 9020, Streamable HTTP on port 9021
4. Zoo Code and SSE-compatible clients connect to `http://127.0.0.1:9020/sse`
5. Kimi Code connects to `http://127.0.0.1:9021/` via Streamable HTTP
6. The single server process serializes all reads/writes — **no race conditions, no data corruption**
7. The server process is **detached** from VS Code — closing the IDE does not kill it

### ⚠️ Warning: stdio Mode

If you manually switch to `"type": "stdio"` (command mode), each VS Code instance spawns its own `crow_mcp_server.py` process. **Two processes writing to the same `crow.bin` will cause silent data loss.** Only use stdio mode if you run exactly one AI client.

### Cross-Editor Compatibility

| Client | Transport | Port | Config File | Auto-Generated |
|--------|-----------|------|-------------|----------------|
| Zoo Code | SSE | 9020 | `mcp_settings.json` (global) | ✅ Yes |
| Cline / Roo Code | SSE | 9020 | `mcp_settings.json` (global) | ✅ Yes |
| Kimi Code | Streamable HTTP | 9021 | `~/.kimi/mcp.json` | ✅ Yes |

---

### Kimi Code Integration

Kimi Code does not support custom modes like Zoo Code's `orchestrator-crow`. Instead, use the single-file [`AGENTS.md`](AGENTS.md) for equivalent Crow Memory integration:

1. Set environment variable: `KIMI_AGENTS_MD=/path/to/crowsmemory/AGENTS.md`
2. Configure MCP in `~/.kimi/mcp.json`:

```json
   {
     "mcpServers": {
       "crow_memory": {
         "transport": "http",
         "url": "http://127.0.0.1:9021/"
       }
     }
   }
   ```

3. The server must run in **dual mode**: `python crow_mcp_server.py --transport dual --port 9020 --http-port 9021`
   (or just use `start_crow_sse.bat` which starts in dual mode by default)

> ⚠️ **Kimi Code does NOT support SSE transport.** It has a known bug where it fails to recognize the MCP SSE `event: endpoint` handshake message, causing an infinite "Testing..." hang or a **405 Method Not Allowed** error. Always use Streamable HTTP (`"transport": "http"`, port 9021) for Kimi Code.

The `AGENTS.md` file provides session-start recall, session-end ingest, and full tool reference — matching the `orchestrator-crow` experience in Zoo Code.

---

## Troubleshooting

### Crow tools don't appear
- **Restart your editor** — MCP settings are read at startup only.
- First launch downloads `nomic-embed-text-v1.5` model (~30-60s). Subsequent launches are fast (~5-10s).
- Verify Python is in PATH: `python --version`
- Check the SSE server is running: visit `http://127.0.0.1:9020/` in a browser — should show "Crow Memory MCP SSE Server"
- Verify global MCP settings have `crow_memory` configured for SSE.

### ECONNREFUSED 127.0.0.1:9020 on VS Code restart
- This is a **race condition** fixed in v1.3.1. The SSE server now runs as a **detached process** that survives VS Code restarts.
- If you still see this: wait 10 seconds and re-run the `Crow SSE Server — Auto Start` task manually (`Ctrl+Shift+P` → `Tasks: Run Task`).
- Verify the server is alive: visit `http://127.0.0.1:9020/` in a browser.

### SSE server not auto-starting
- Verify Task Scheduler registration: `schtasks /query /tn "CrowMemoryAuto"`
- Check server health: visit `http://127.0.0.1:9020/health`
- View server logs: `type sse_server.log`
- Manually start: run [`start_crow_sse.bat`](start_crow_sse.bat)
- Re-register: `powershell -File scripts/register_crow_task.ps1`

### Port 9020 already in use
- [`start_crow_sse.bat`](start_crow_sse.bat) detects this and skips duplicate starts automatically
- To force restart: kill the process on port 9020, delete `memory\crow.bin.lock`, then re-open the workspace

### Recall returns empty hints (no fabricated text)
- Normal! Crow only returns memories above the similarity cutoff (0.35). Below it, you get an empty hints list with confidence 0 — no filler text (v1.5.0 removed the old "faint bias" placeholders). Crow needs 20-30+ ingestions before meaningful hints emerge. Keep coding.
- Enable AUTO-INGEST by switching to **"Orchestrator + Crow"** mode — the AI will learn proactively.

### UnicodeEncodeError: 'cp949' codec can't encode character (Korean Windows)

**Symptoms**: Zoo Code shows `UnicodeEncodeError: 'cp949' codec can't encode character...`.

**Root cause**: Korean Windows uses `cp949` (EUC-KR) as the default system encoding. When MCP clients process SSE responses containing Unicode characters (✓, Korean text, emoji), the `cp949` codec fails because it cannot represent these characters.

**Affected languages** (any non-UTF-8 Windows locale):
| Language | Code Page | Issue |
|----------|-----------|-------|
| Korean (한국어) | `cp949` | Unicode checkmarks, Korean characters |
| Japanese (日本語) | `cp932` | Shift-JIS can't encode certain Unicode symbols |
| Chinese Simplified (简体中文) | `cp936` | GBK encoding conflicts |
| Chinese Traditional (繁體中文) | `cp950` | Big5 encoding conflicts |
| Thai (ไทย) | `cp874` | Thai + Unicode mixing issues |
| Any non-Unicode Windows locale | various | Same class of problem |

**Fix A — Enable Windows UTF-8 mode (recommended, permanent)**

1. `Win + R` → `intl.cpl` → Enter
2. **Administrative** tab → **Change system locale...**
3. Check ✅ **Beta: Use Unicode UTF-8 for worldwide language support**
4. OK → **Restart Windows**

Or via PowerShell (Admin):
```powershell
Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\Nls\CodePage" -Name "ACP" -Value "65001"
```

**Fix B — Environment variables (already applied by installer)**

[`start_crow_sse.bat`](start_crow_sse.bat) sets `PYTHONUTF8=1` and `PYTHONIOENCODING=utf-8`, and runs Python with `-X utf8` flag. [`crow_mcp_server.py`](crow_mcp_server.py) enforces UTF-8 stdout/stderr at startup. These prevent most encoding issues on the server side, but client-side encoding requires Fix A.

### PermissionError / lock file issues
- Delete stale lock: `del memory\crow.bin.lock` (Windows) or `rm memory/crow.bin.lock` (macOS/Linux)
- [`start_crow_sse.bat`](start_crow_sse.bat) automatically cleans stale locks before starting

---

## REST API Endpoints

Crow Memory Server also provides REST API alongside the MCP SSE protocol.
VibeZoo Bridge and other tools can communicate directly with Crow Memory over HTTP.

### `GET /health`
Check server health:
```json
{"status": "ok", "version": "1.5.0", "entries": 42}
```

### `POST /ingest`
Store new memory:
```json
{"content": "...", "register": "context", "source": "rest_api", "tags": [], "project": null}
```

### `GET /recall?query=...&register=...&limit=5&project=...&strict_project=false`
Search memories (params: `query`, `register` (single or `all` → multi-register merge), `limit` (1-20, default 5), `project`, `strict_project`):
```json
{"results": [{"content": "...", "score": 0.95, ...}], "count": 1}
```

### How to Run
```bash
# SSE + REST API (default, recommended)
python crow_mcp_server.py --transport dual --port 9020 --http-port 9021

# SSE only
python crow_mcp_server.py --transport sse --port 9020

# Verify REST API + health check
curl http://127.0.0.1:9020/health
```

### Windows Auto-Start (v1.5.0+)

The server is registered as a Windows Task Scheduler task during installation. To manually register or unregister:

```bash
# Register auto-start
powershell -File scripts/register_crow_task.ps1

# Check status
schtasks /query /tn "CrowMemoryAuto"

# Remove auto-start
schtasks /delete /tn "CrowMemoryAuto" /f
```

For manual server start without auto-registration, use [`start_crow_sse.bat`](start_crow_sse.bat).

---

## Architecture

See [`CROW_MEMORY_ARCHITECTURE.md`](CROW_MEMORY_ARCHITECTURE.md) for the full technical specification including mathematical foundations, Hebbian EMA update rules, spectral clipping, and capacity bounds.

---

## License

MIT License — see [`LICENSE`](LICENSE) for details.

---

## Commercial Services

Crow Memory is open-source and free to use under MIT. But every organization has unique needs — different security requirements, proprietary LLM integrations, custom encoding schemes, or industry-specific compliance mandates.

**We offer custom development services for:**

- 🔒 **Security-hardened deployments** — Air-gap environments, on-premise only, encrypted `crow.bin` storage, audit logging, RBAC integration
- 🏢 **Enterprise customization** — Custom register dimensions, industry-specific decay profiles (finance, healthcare, legal), dedicated SLA-backed MCP server clusters
- 🤖 **LLM-specific optimization** — Fine-tuned embedding models, custom projection layers, optimized weight matrices for specific LLM architectures (Claude, GPT, DeepSeek, Gemini, local models)
- 🧩 **Software integration** — Plugin-style Crow integration for non-VS Code IDEs, CI/CD pipeline hooks, custom build event detectors
- 🌐 **Additional language support** — Beyond the 36 VS Code locales, we can add translation support for any language or domain-specific terminology
- 📊 **Enterprise analytics** — Memory usage dashboards, team-wide style consistency monitoring, drift alerting

> **For security-enhanced, enterprise-grade, or custom LLM/software-tailored Crow Memory development:**

📧 **myk1yt@gmail.com**

*"If you share this philosophy and want to take Crow further — whether for your team, your product, or your enterprise — let's build it together."*

---

*Crow Memory v1.5.0 — September 2026*
*Co-designed by Stefano,Kim & AI*

crowmemory

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README