# kenstar2017/memory_sandbox architecture

> Architecture diagram of the GitHub repository kenstar2017/memory_sandbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kenstar2017/memory_sandbox
- Repository: https://github.com/kenstar2017/memory_sandbox

## Overview

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: [`core/sandbox.py`](https://github.com/kenstar2017/memory_sandbox/blob/main/core/sandbox.py) (Memory Sandbox), [`desktop/src/App.tsx`](https://github.com/kenstar2017/memory_sandbox/blob/main/desktop/src/App.tsx) (Desktop UI), [`app_web.py`](https://github.com/kenstar2017/memory_sandbox/blob/main/app_web.py) (Web API), [`core/long_term.py`](https://github.com/kenstar2017/memory_sandbox/blob/main/core/long_term.py) (Long-term Memory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_desktop["Desktop UI<br/>[App.tsx]"]
  node_desktop_api["Desktop API Client<br/>[client.ts]"]
  node_web["Web API<br/>[app_web.py]"]
  node_cli["CLI<br/>[main.py]"]
  node_mcp["MCP Server<br/>[mcp_server.py]"]
end

subgraph group_memory["Memory Runtime"]
  node_sandbox["Memory Sandbox<br/>[sandbox.py]"]
  node_sensory["Sensory Memory<br/>[sensory.py]"]
  node_working["Working Memory<br/>[working.py]"]
  node_rules["Procedural Rules<br/>[rules.py]"]
  node_longterm[("Long-term Memory<br/>[long_term.py]")]
  node_embedding["Embedding<br/>[embedding.py]"]
  node_bm25["BM25 Search<br/>[bm25.py]"]
  node_llm["LLM Adapter<br/>[llm.py]"]
end

subgraph group_knowledge["Knowledge &amp; Feishu"]
  node_knowledge_store[("Knowledge Base<br/>[knowledge.py]")]
  node_knowledge_ingest["Document Ingest"]
  node_feishu["Feishu Documents<br/>[feishu.py]"]
end

subgraph group_integration["Agent Integration"]
  node_hooks["Cursor Hook Manager<br/>[cursor_hooks.py]"]
  node_prefetch["Prompt Prefetch<br/>[memory-prefetch.py]"]
  node_prepare_gate["Prepare Gate"]
end

subgraph group_platform["Configuration"]
  node_config["Configuration<br/>[config.py]"]
end

node_user(("User"))
node_hook_actor(("Cursor Agent"))

node_user -->|"asks or remembers"| node_desktop
node_user -->|"submits input"| node_web
node_user -->|"runs commands"| node_cli
node_user -->|"requests memory"| node_mcp
node_desktop -->|"calls"| node_desktop_api
node_desktop_api -->|"sends API requests"| node_web
node_web -.->|"serves memory operations"| node_sandbox
node_cli -.->|"builds and queries"| node_sandbox
node_mcp -.->|"exposes memory tools"| node_sandbox
node_sandbox -->|"filters input"| node_sensory
node_sandbox -->|"checks context"| node_working
node_sandbox -->|"applies rules"| node_rules
node_sandbox -->|"retrieves and consolidates"| node_longterm
node_sandbox -->|"falls back to"| node_llm
node_longterm -.->|"uses vectors"| node_embedding
node_longterm -.->|"uses text ranking"| node_bm25
node_desktop -->|"lists knowledge"| node_knowledge_store
node_desktop -->|"adds documents"| node_knowledge_ingest
node_knowledge_ingest -->|"fetches documents"| node_feishu
node_knowledge_ingest -->|"records documents"| node_knowledge_store
node_hook_actor -->|"submits prompt"| node_prefetch
node_prefetch -->|"posts prepare request"| node_web
node_hook_actor -->|"invokes tools"| node_prepare_gate
node_hooks -->|"installs script"| node_prefetch
node_hooks -->|"installs script"| node_prepare_gate
node_config -.->|"configures runtime"| node_sandbox

click node_desktop "https://github.com/kenstar2017/memory_sandbox/blob/main/desktop/src/App.tsx"
click node_desktop_api "https://github.com/kenstar2017/memory_sandbox/blob/main/desktop/src/api/client.ts"
click node_web "https://github.com/kenstar2017/memory_sandbox/blob/main/app_web.py"
click node_cli "https://github.com/kenstar2017/memory_sandbox/blob/main/main.py"
click node_mcp "https://github.com/kenstar2017/memory_sandbox/blob/main/mcp_server.py"
click node_sandbox "https://github.com/kenstar2017/memory_sandbox/blob/main/core/sandbox.py"
click node_sensory "https://github.com/kenstar2017/memory_sandbox/blob/main/core/sensory.py"
click node_working "https://github.com/kenstar2017/memory_sandbox/blob/main/core/working.py"
click node_rules "https://github.com/kenstar2017/memory_sandbox/blob/main/core/rules.py"
click node_longterm "https://github.com/kenstar2017/memory_sandbox/blob/main/core/long_term.py"
click node_embedding "https://github.com/kenstar2017/memory_sandbox/blob/main/core/embedding.py"
click node_bm25 "https://github.com/kenstar2017/memory_sandbox/blob/main/core/bm25.py"
click node_llm "https://github.com/kenstar2017/memory_sandbox/blob/main/core/llm.py"
click node_knowledge_store "https://github.com/kenstar2017/memory_sandbox/blob/main/core/knowledge.py"
click node_knowledge_ingest "https://github.com/kenstar2017/memory_sandbox/blob/main/core/knowledge_ingest.py"
click node_feishu "https://github.com/kenstar2017/memory_sandbox/blob/main/core/feishu.py"
click node_hooks "https://github.com/kenstar2017/memory_sandbox/blob/main/core/cursor_hooks.py"
click node_prefetch "https://github.com/kenstar2017/memory_sandbox/blob/main/cursor_hooks/memory-prefetch.py"
click node_prepare_gate "https://github.com/kenstar2017/memory_sandbox/blob/main/cursor_hooks/memory-require-prepare.py"
click node_config "https://github.com/kenstar2017/memory_sandbox/blob/main/core/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_desktop,node_desktop_api,node_web,node_cli,node_mcp,node_user toneBlue
class node_sandbox,node_sensory,node_working,node_rules,node_longterm,node_embedding,node_bm25,node_llm toneAmber
class node_knowledge_store,node_knowledge_ingest,node_feishu toneMint
class node_hooks,node_prefetch,node_prepare_gate toneRose
class node_config,node_hook_actor toneIndigo
```

## Components

### User Interfaces

- [Desktop UI](https://github.com/kenstar2017/memory_sandbox/blob/main/desktop/src/App.tsx): `desktop/src/App.tsx`
- [Desktop API Client](https://github.com/kenstar2017/memory_sandbox/blob/main/desktop/src/api/client.ts): `desktop/src/api/client.ts`
- [Web API](https://github.com/kenstar2017/memory_sandbox/blob/main/app_web.py): `app_web.py`
- [CLI](https://github.com/kenstar2017/memory_sandbox/blob/main/main.py): `main.py`
- [MCP Server](https://github.com/kenstar2017/memory_sandbox/blob/main/mcp_server.py): `mcp_server.py`

### Memory Runtime

- [Memory Sandbox](https://github.com/kenstar2017/memory_sandbox/blob/main/core/sandbox.py): `core/sandbox.py`
- [Sensory Memory](https://github.com/kenstar2017/memory_sandbox/blob/main/core/sensory.py): `core/sensory.py`
- [Working Memory](https://github.com/kenstar2017/memory_sandbox/blob/main/core/working.py): `core/working.py`
- [Procedural Rules](https://github.com/kenstar2017/memory_sandbox/blob/main/core/rules.py): `core/rules.py`
- [Long-term Memory](https://github.com/kenstar2017/memory_sandbox/blob/main/core/long_term.py): `core/long_term.py`
- [Embedding](https://github.com/kenstar2017/memory_sandbox/blob/main/core/embedding.py): `core/embedding.py`
- [BM25 Search](https://github.com/kenstar2017/memory_sandbox/blob/main/core/bm25.py): `core/bm25.py`
- [LLM Adapter](https://github.com/kenstar2017/memory_sandbox/blob/main/core/llm.py): `core/llm.py`

### Knowledge & Feishu

- [Knowledge Base](https://github.com/kenstar2017/memory_sandbox/blob/main/core/knowledge.py): `core/knowledge.py`
- [Document Ingest](https://github.com/kenstar2017/memory_sandbox/blob/main/core/knowledge_ingest.py): `core/knowledge_ingest.py`
- [Feishu Documents](https://github.com/kenstar2017/memory_sandbox/blob/main/core/feishu.py): `core/feishu.py`

### Agent Integration

- [Cursor Hook Manager](https://github.com/kenstar2017/memory_sandbox/blob/main/core/cursor_hooks.py): `core/cursor_hooks.py`
- [Prompt Prefetch](https://github.com/kenstar2017/memory_sandbox/blob/main/cursor_hooks/memory-prefetch.py): `cursor_hooks/memory-prefetch.py`
- [Prepare Gate](https://github.com/kenstar2017/memory_sandbox/blob/main/cursor_hooks/memory-require-prepare.py): `cursor_hooks/memory-require-prepare.py`

### Configuration

- [Configuration](https://github.com/kenstar2017/memory_sandbox/blob/main/core/config.py): `core/config.py`

### Other components

- **User**
- **Cursor Agent**

## Connections

- User → Desktop UI: asks or remembers (evidence: `README.md`)
- User → Web API: submits input (evidence: `README.md`)
- User → CLI: runs commands (evidence: `README.md`)
- User → MCP Server: requests memory (evidence: `README.md`)
- Desktop UI → Desktop API Client: calls (evidence: `desktop/src/App.tsx`)
- Desktop API Client → Web API: sends API requests (evidence: `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 (evidence: `README.md`)
- Memory Sandbox → Working Memory: checks context (evidence: `README.md`)
- Memory Sandbox → Procedural Rules: applies rules (evidence: `README.md`)
- Memory Sandbox → Long-term Memory: retrieves and consolidates (evidence: `README.md`)
- Memory Sandbox → LLM Adapter: falls back to (evidence: `README.md`)
- Long-term Memory → Embedding: uses vectors
- Long-term Memory → BM25 Search: uses text ranking
- Desktop UI → Knowledge Base: lists knowledge (evidence: `desktop/src/App.tsx`)
- Desktop UI → Document Ingest: adds documents (evidence: `desktop/src/App.tsx`)
- Document Ingest → Feishu Documents: fetches documents (evidence: `core/knowledge_ingest.py`)
- Document Ingest → Knowledge Base: records documents (evidence: `core/knowledge_ingest.py`)
- Cursor Agent → Prompt Prefetch: submits prompt (evidence: `README.md`)
- Prompt Prefetch → Web API: posts prepare request (evidence: `README.md`)
- Cursor Agent → Prepare Gate: invokes tools (evidence: `README.md`)
- Cursor Hook Manager → Prompt Prefetch: installs script (evidence: `README.md`)
- Cursor Hook Manager → Prepare Gate: installs script (evidence: `README.md`)
- Configuration → Memory Sandbox: configures runtime