本地嵌入: bge-small-zh-v1.5（24MB），纯 CPU，无需 GPU/API Key/联网。冷启动约 14 秒（首次预热全库向量 + 检索索引），之后查询延迟仅比纯规则多 118ms（164→282ms）。嵌入在排序质量上有增益（NDCG +0.01, MRR +0.01），在真实场景的语义理解（同义词、改写、跨语言）中价值更大。

运行基准：pip install "memory-garden[embeddings]" && python -m benchmarks.retrieval --dataset medium --baselines default --output docs/reports/benchmark_v2.json

检索策略可通过 GardenRuntimeConfig.retrieval.strategy 配置：fts_only（纯全文，最快）、fts_with_vector_rescore（默认，平衡）、full_hybrid（全量向量召回，最慢但覆盖面最大）。

优化路径（Ablations）

graph TD
    A["FTS5 原始<br/>40% recall · 3ms · 0规则"] -->|"CJK ngram 修复<br/>中文从0%复活"| B["FTS5 CJK<br/>40% recall · 3ms · 312 QPS"]
    B -->|"+ 规则评分管线<br/>+3pp · 可解释"| C["Product 规则<br/>43% recall · 553ms"]
    C -->|"+ 特征向量<br/>回溯力增强"| D["+ 特征评分<br/>43% recall · 539ms"]
    D -->|"+ 候选截断+预分词+NumPy<br/>-48%延迟"| E["+ 组合优化<br/>43% recall · 260ms"]
    E -->|"+ 写入时索引<br/>token/embed预计算"| F["当前<br/>43% recall · 164ms<br/>累计-70%延迟"]
    style A fill:#f0f0f0
    style F fill:#4caf50,color:#fff

延迟分布

行业对比（同数据、同查询）

在 medium 数据集上与 ChromaDB（默认 all-MiniLM-L6-v2）和 FAISS Flat（bge-small-zh-v1.5）同条件对比。完整 JSON 见 docs/reports/comparison_benchmark.json。

运行：pip install "memory-garden[bench,embeddings]" && python -m benchmarks.comparison --dataset medium --output docs/reports/comparison_benchmark.json --markdown docs/reports/comparison_benchmark.md

为什么选择 Memory Garden

Why Memory Garden

An agent can chat with you for 50 turns and still forget that you prefer short Chinese replies with English technical terms. Plain vector recall can retrieve similar text, but it often lacks provenance, deletion proof, and policy boundaries.

Memory Garden does not claim to modify a Transformer's internal attention mechanism. It mitigates the practical symptom of attention drop in long conversations by selecting durable, relevant memory outside the live context window and reintroducing it only when needed. The core is a memory layer; the skill form is one delivery surface for that capability.

Memory Garden treats memory as a lifecycle:

User message -> Seed -> Court -> Growth -> Dream -> Harvest -> Brief -> Agent

Every long-term memory is traceable to source ids. Content that cannot be traced does not enter durable memory.

Quickstart

pip install memory-garden
memory-garden demo
memory-garden health

For optional LLM assistance, prefer environment variables:

export DEEPSEEK_API_KEY="..."

from memory_garden.sdk import MemoryGarden

garden = MemoryGarden.local("./my_garden")
skill = garden.as_skill().with_deepseek()

Claude Code hook usage:

python -m memory_garden.integrations.adapters.claude_code before
python -m memory_garden.integrations.adapters.claude_code after

Adapter CLIs stay rules-only by default. If you explicitly want them to auto-load provider credentials from environment variables or local provider_config.json, set MEMORY_GARDEN_ENABLE_PROVIDER_AUTOLOAD=1 for that session.

Install as a Codex Skill

The distributable skill lives in packaging/codex-skills/memory-garden. The skill does not vendor the Python package, so install memory-garden in the Python environment used by your agent host first:

pip install memory-garden

For local development from this repository:

python -m pip install -e . --no-deps

Then copy the skill folder into Codex's skill discovery directory.

PowerShell:

$skills = "$env:USERPROFILE\.codex\skills"
New-Item -ItemType Directory -Force -Path $skills | Out-Null
Copy-Item -Recurse -Force ".\packaging\codex-skills\memory-garden" "$skills\memory-garden"
python "$skills\memory-garden\scripts\memory_garden_skill_smoke.py"

macOS/Linux:

mkdir -p ~/.codex/skills
cp -R packaging/codex-skills/memory-garden ~/.codex/skills/memory-garden
python ~/.codex/skills/memory-garden/scripts/memory_garden_skill_smoke.py

The skill is explicit by default (allow_implicit_invocation: false). In a new Codex session, call it directly:

Use $memory-garden to retrieve relevant local memory before answering this task.
Use $memory-garden to propose a memory from this note, but do not approve it yet.
Use $memory-garden to forget memory id <id> and report the proof.

Use From Another Program

Use the Python SDK when your application owns the conversation loop. Choose a garden home outside the repository and keep it out of Git.

from memory_garden.sdk import MemoryGarden

garden = MemoryGarden.local("./.memory_garden")
skill = garden.as_skill()

try:
    skill.open_session()

    # Reviewable write: creates proposals only.
    proposals = skill.propose_memory("remember: prefer concise release notes")
    if proposals:
        card = skill.approve_memory_proposal(proposals[0].id)

    # Trusted write: use only when your app policy allows auto-approval.
    result = skill.remember_memory(
        "remember: prefer dark mode dashboards",
        mode="trusted",
    )

    query = "How should I format this release note?"
    brief = skill.build_memory_brief(
        query,
        context={"project_id": "atlas", "task_type": "writing"},
    )

    messages = [
        {"role": "system", "content": brief.use},
        {"role": "user", "content": query},
    ]
    assistant_reply = call_your_model(messages)
    skill.after(query, assistant_reply)
finally:
    garden.close()

For a hook-style integration around each model call:

ctx = skill.before(
    user_message,
    messages=[{"role": "user", "content": user_message}],
)
assistant_reply = call_your_model(ctx.messages)
skill.after(user_message, assistant_reply)

By default this is local and rules-only: no LLM, embedding, reranker, or network provider is called. If your application owns external providers, register them explicitly with ProviderRegistry and an opt-in ProviderPolicy.

Integration

Claude Code:

from memory_garden.sdk import MemoryGarden
from memory_garden.integrations.adapters.claude_code import ClaudeCodeSession

garden = MemoryGarden.local("./my_garden")
session = ClaudeCodeSession(garden=garden)
context = session.before(user_message="How should I reply?")
session.after(assistant_reply="...")
session.close()

Custom agent via skill API:

skill = garden.as_skill()
ctx = skill.before("I prefer short replies.")
reply = call_your_model(ctx.brief_text)
skill.after("I prefer short replies.", reply)

Session commands

• 花花开 (Hua Hua Kai) opens a garden session and begins harvesting memory.
• 花花关 (Hua Hua Guan) closes the session and emits structured feedback.

Control commands are never stored as user memory.

Effect

Older rule-only briefs expose source identifiers in the human-facing text:

[use] If relevant, reference memory ids: id1, id2, id3, id4.

With an LLM brief writer configured, the hook injects a natural-language summary while retaining source ids internally:

[use] The user prefers short replies in Chinese, with technical terms kept in English. They mainly use VS Code and Go/Rust for backend work.

Architecture

Core       Seed, Court, Growth, Dream, Harvest, Brief
Covenant   Policy, trust rules, visibility boundaries
Harvest    Local retrieval, ranking, and source-preserving briefs
Cognition  Optional LLM enhancement for harvest-time writing and ranking
Product    Proposal review, versioning, retrieval, forget proof
Soil       Local home, SQLite storage, FTS index, health checks
Adapters   Claude Code, Codex, Hermes, OpenAI/Anthropic, LangChain, LangGraph, FastAPI, LlamaIndex

The default rules-only behavior remains stable. LLM output is validated with Pydantic and must carry traceable source_ids, memory_ids, or seed_ids.

Tech Stack

Memory Garden is intentionally small at runtime and explicit at integration boundaries:

Notably absent by default: no vector database, no background service, no mandatory cloud API, and no heavy framework dependency in the core package.

Integration

Claude Code:

from memory_garden.sdk import MemoryGarden
from memory_garden.integrations.adapters.claude_code import ClaudeCodeSession

garden =