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."

---

Crow Memory

"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):

git clone https://github.com/myk1yt/crowmemory.git
cd crowmemory
.\install.ps1

macOS / Linux:

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 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 → 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	Project-level Zoo configuration — default mode, version, Crow auto-recall/ingest flags
.zoo/config.schema.json	JSON Schema for .zoo/config.json validation
.roo/mcp.schema.json	JSON Schema for .roo/mcp.json MCP configuration validation

Default Mode

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

Templates

The templates/ directory contains reusable configuration templates:

Template	Description
templates/zoo-config.json	Template for .zoo/config.json with Crow Memory defaults
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 (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	Migrate legacy value_bank entries (sanitize + add project field). Runs in dry-run by default; pass --apply to write.
scripts/merge_value_bank.py	Merge value_bank files (dedupe, resolve conflicts). Dry-run by default; --apply to write.
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 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/.

---

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 auto-runs 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 for equivalent Crow Memory integration:

1. Set environment variable: KIMI_AGENTS_MD=/path/to/crowsmemory/AGENTS.md

2. Configure MCP in ~/.kimi/mcp.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
• Re-register: powershell -File scripts/register_crow_task.ps1

Port 9020 already in use

• 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):

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 sets PYTHONUTF8=1 and PYTHONIOENCODING=utf-8, and runs Python with -X utf8 flag. 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 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:

{"status": "ok", "version": "1.5.0", "entries": 42}

POST /ingest

Store new memory:

{"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):

{"results": [{"content": "...", "score": 0.95, ...}], "count": 1}

How to Run

# 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:

# 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.

---

Architecture

See 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 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