How kenstar2017/memory_sandbox works
Memory Sandbox is a local layered memory product, exposed through CLI, MCP, web, and desktop interfaces. Its documented recall flow passes input through sensory filtering, working context and rules, then persistent long-term retrieval; a local hit can answer directly, otherwise the LLM is the fallback. Results are consolidated back into memory. The repository also includes document knowledge ingestion, Feishu integrations, and Cursor hooks for retrieval-before-work and memory maintenance. Some backend modules were not sampled, so uncertain internal call links are omitted rather than inferred.
Main entry points: sandbox.py Memory Sandbox · App.tsx Desktop UI · app_web.py Web API · long_term.py Long-term Memory
Components 22
User Interfaces
- Desktop UI
desktop/src/App.tsx - Desktop API Client
desktop/src/api/client.ts - Web API
app_web.py - CLI
main.py - MCP Server
mcp_server.py
Memory Runtime
- Memory Sandbox
core/sandbox.py - Sensory Memory
core/sensory.py - Working Memory
core/working.py - Procedural Rules
core/rules.py - Long-term Memory
core/long_term.py - Embedding
core/embedding.py - BM25 Search
core/bm25.py - LLM Adapter
core/llm.py
Knowledge & Feishu
- Knowledge Base
core/knowledge.py - Document Ingest
core/knowledge_ingest.py - Feishu Documents
core/feishu.py
Agent Integration
- Cursor Hook Manager
core/cursor_hooks.py - Prompt Prefetch
cursor_hooks/memory-prefetch.py - Prepare Gate
cursor_hooks/memory-require-prepare.py
Configuration
- Configuration
core/config.py
Other components
- User
- Cursor Agent
Connections 26
- User → Desktop UI: asks or remembers
README.md - User → Web API: submits input
README.md - User → CLI: runs commands
README.md - User → MCP Server: requests memory
README.md - Desktop UI → Desktop API Client: calls
desktop/src/App.tsx - Desktop API Client → Web API: sends API requests
desktop/src/api/client.ts - Web API → Memory Sandbox: serves memory operations
- CLI → Memory Sandbox: builds and queries
- MCP Server → Memory Sandbox: exposes memory tools
- Memory Sandbox → Sensory Memory: filters input
README.md - Memory Sandbox → Working Memory: checks context
README.md - Memory Sandbox → Procedural Rules: applies rules
README.md - Memory Sandbox → Long-term Memory: retrieves and consolidates
README.md - Memory Sandbox → LLM Adapter: falls back to
README.md - Long-term Memory → Embedding: uses vectors
- Long-term Memory → BM25 Search: uses text ranking
- Desktop UI → Knowledge Base: lists knowledge
desktop/src/App.tsx - Desktop UI → Document Ingest: adds documents
desktop/src/App.tsx - Document Ingest → Feishu Documents: fetches documents
core/knowledge_ingest.py - Document Ingest → Knowledge Base: records documents
core/knowledge_ingest.py - Cursor Agent → Prompt Prefetch: submits prompt
README.md - Prompt Prefetch → Web API: posts prepare request
README.md - Cursor Agent → Prepare Gate: invokes tools
README.md - Cursor Hook Manager → Prompt Prefetch: installs script
README.md - Cursor Hook Manager → Prepare Gate: installs script
README.md - Configuration → Memory Sandbox: configures runtime