convez.ai
AgenteAutomaçãoAvançado
wuzishu3-web

Agent Memory Vault

wuzishu3-web/agent-memory-vault

Memória durável e indexada para agentes IA que não esquecem

Ver no GitHub
InicialPluginScore · de 0 a 100

Sistema de memória persistente e compartilhada para agentes IA, construído sobre um vault Markdown/Obsidian. Automatiza a manutenção de uma base de conhecimento estruturada com cross-linking, deduplicação e indexação, transformando RAG estático em um wiki vivo e mantido continuamente.

Instalação

$npx convez-ai wuzishu3-web/agent-memory-vault

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Manter contexto persistente entre sessões de agentes de coding
  • Construir bases de conhecimento auto-mantidas com deduplicação automática
  • Ingerir fontes externas (artigos, vídeos, repositórios) como notas interligadas
  • Hybrid retrieval (vector + keyword + graph) para consultas de contexto

Veredito

Ferramenta sólida e bem-pensada que resolve um problema real: RAG estático que joga fora conhecimento a cada sessão. A pipeline de ingest automático + hot cache + relações zero-LLM é prática. Depende só de PyYAML e endpoints OpenAI-compatíveis, o que reduz fricção. Exige engenharia de prompts e integração própria com agentes (não é plug-and-play).

README

A tradução para o português deste README ainda está na fila.

agent-memory-vault

Stop letting your AI agents forget. A shared, persistent memory + knowledge-ingest engine over a plain Markdown vault.

CI License: MIT Python Dependencies

architecture

A persistent, shared long-term memory + knowledge-ingest system for AI coding agents (Claude Code, Codex, and friends), built on a plain Markdown / Obsidian-compatible vault.

Your agents stop forgetting. Instead of re-retrieving raw files on every query (classic RAG), they compile knowledge into a maintained vault of structured notes — and keep it cross-linked, deduplicated, and indexed automatically.

Inspired by Andrej Karpathy's LLM Wiki Pattern (knowledge expression layer) and the GBrain idea of a continuously-running knowledge system (knowledge runtime layer). This project is both: a writable wiki of pages plus the engine that keeps it alive.


The problem it solves

Most "give the AI a knowledge base" setups are just temporary retrieval: you dump PDFs/notes in, the system grabs a few chunks, the model stitches an answer — then it's gone. Ask twice, get two answers. New material doesn't reorganize old knowledge. Nothing accumulates.

agent-memory-vault flips it: knowledge is written down once, as durable structured pages, then maintained. The tedious part of a knowledge base isn't reading or thinking — it's the bookkeeping (cross-references, dedup, indexes, consistency). That's exactly what agents do reliably, so this system automates it.

Key features

CapabilityScriptWhat it does
🚀 Boot contextagent_memory_boot.pyOne command prints the hot cache + recent log + task-relevant hits, so any agent starts a session already oriented.
✍️ Structured writeagent_memory.pyWrite a typed note (decision / knowledge / project / source / …) with frontmatter; auto-appends the log and the section index.
🔥 Hot cacheupdate_hot.pyA ~500-word "where are we right now" snapshot every agent reads first. Overwrite-on-change, file-locked for concurrent agents.
🔎 Hybrid retrievalquery_vault.pyVector (cosine) + keyword search fused with RRF, plus a one-hop lookup over the relation graph.
🧮 Vector indexbuild_embeddings.pyIncremental embeddings (content-hash based) via any OpenAI-compatible embedding endpoint.
🕸️ Relation graphextract_relations.pyZero-LLM, regex + whitelist relation extraction (works_at / reports_to / founded / …).
⭐ Ingest pipelineingest.pyTurn any external source (article / video / repo / transcript) into a page + bidirectional cross-references to the most similar existing notes + a quality gate + index rebuild. The piece classic RAG and plain note-taking both skip.
🛡️ Auto-ingest hookingest_stop_hook.pyA Claude Code Stop hook: if a session processed an external source but never ingested it, it reminds the agent (once) to file it — using the agent's own analysis, never a cheap auto-summary.
🧹 Lintvault_health_check.pyFinds stale inbox drafts, overdue 待核验 notes, orphan pages, incomplete frontmatter.
🌙 Consolidationdream_cycle.pyPeriodic "dreaming" pass that reorganizes/promotes knowledge.
📓 Session beatsstop_hook_beat.pyConservative Stop hook that records what a session touched (redacts secrets).

The star: the ingest pipeline

python3 scripts/ingest.py --agent claude-code \
  --title "LLM Wiki Pattern vs GBrain" \
  --summary "<your high-quality summary, written by the agent>" \
  --body-file notes.md \
  --url "https://example.com/article" \
  --source-type article

What happens, deterministically:

  1. Dedup — checks the source dir by URL / title; updates instead of duplicating.
  2. Quality gate — if the summary/body is too thin, the source is quarantined to the inbox with status: 待核验 and never pollutes your source folder. No half-baked pages, ever.
  3. Write page — a structured source note with frontmatter, appended to the log and source index.
  4. Bidirectional cross-references — embeds the new page, finds the top-K most semantically similar existing notes (cosine ≥ threshold), and writes [[links]] both ways — into the new page and back into each old page. This is the "bookkeeping" that keeps a wiki from rotting.
  5. Re-index — incremental embeddings + relation extraction.

Design principle: understanding vs bookkeeping are separated. The summary must come from a capable agent in-context (high quality); the script only does the mechanical filing. That's why it can be fully automatic without producing junk.

Demo

Ingesting a source automatically threads it into your existing knowledge:

$ python3 scripts/ingest.py --agent claude-code \
    --title "Hybrid Retrieval Explained" \
    --summary "Vector cosine + keyword via RRF, plus a relation-graph one-hop lookup." \
    --url "https://example.com/hybrid" --source-type article

# → writes  08_Sources/2026-…-Hybrid-Retrieval-Explained.md   (quality gate: passed)
# → finds the most similar existing note (cosine 0.752) and links it BOTH ways:
#     new page  ──▶  04_Knowledge/…-Vector-retrieval-deep-dive.md
#     that note ──▶  back to the new page          ← the bookkeeping a wiki usually rots without
# → rebuilds the embedding + relation indexes (incremental)

If the embedding endpoint is offline, the page is still written and logged — only the cross-references and re-index are skipped (and the page is flagged for later).

How it works (architecture)

        ┌─────────────────────────── your agents ───────────────────────────┐
        │   Claude Code        Codex          (your own agent)               │
        └───────────┬───────────────┬───────────────┬───────────────────────┘
                    │ boot / write / query / ingest  │
        ┌───────────▼────────────────────────────────▼───────────────────────┐
        │                      shared Markdown vault                          │
        │                                                                     │
        │  EXPRESSION layer (LLM Wiki)        RUNTIME layer (GBrain)           │
        │  • typed pages (00..10)             • embeddings.json (vectors)      │
        │  • [[wikilinks]] graph              • relations.json (entities)      │
        │  • WRITE_GUIDE (schema/rules)       • log.md (timeline)              │
        │  • index pages                      • hot.md (working memory)        │
        │                                     • ingest + lint + dream loops    │
        └─────────────────────────────────────────────────────────────────────┘

Vault layout

your-vault/
├── index.md                      # home / catalog
├── AGENTS.md                     # operating rules agents read
├── 00_Inbox/                     # unsorted + quarantined drafts
├── 01_User/profile.md            # stable user preferences & background
├── 02_Agents/                    # one profile per agent
├── 03_Projects/  04_Knowledge/  05_Daily/
├── 06_Decisions/ 07_Playbooks/  08_Sources/   # ← ingest writes here
├── 09_Archive/   10_Resume/
└── _system/
    ├── WRITE_GUIDE.md            # the single authority: what goes where
    ├── AGENT_MEMORY_PROTOCOL.md  # the protocol all agents follow
    ├── hot.md  log.md            # working memory + timeline
    ├── embeddings.json relations.json   # generated indexes (gitignored)
    └── scripts/ → (this repo's scripts/)

What this is — and isn't

Agent memory is a crowded space, and several mature projects beat this one on raw capability. Saying so plainly is the point: it helps you tell whether this is the right tool for you rather than the "best" one in the abstract.

This is for you if you:

  • run multiple, heterogeneous CLI / coding agents (Claude Code, Codex, …) and want them to share one brain;
  • want memory to be plain Markdown files you own — greppable, hand-editable, git-versionable, openable in Obsidian — not rows in a vector DB;
  • prefer local-first, zero-service, tiny-dependency (one library + an embedding endpoint) over a framework or a hosted API;
  • like the "compile knowledge into maintained, cross-linked pages" stance over "retrieve raw chunks on every query".

Look elsewhere if you:

  • need to scale to millions of memories — brute-force cosine over a JSON file won't cut it;
  • want autonomous, self-managing memory or sophisticated temporal/graph retrieval out of the box;
  • are embedding memory into a product/app and want a maintained SDK + integrations.

How it compares

design centermemory lives inshines when
agent-memory-vault (this)files you own, shared by a fleet of CLI agentsa Markdown / Obsidian vaultlocal power user · multi-agent · human-readable knowledge
Mem0a memory layer/SDK for LLM appsvector + graph storeauto-extracting memory into your own app
Letta / MemGPTstateful agents with self-editing memoryagent server + DBautonomous, self-managing agent memory
Zep / Graphitia production memory backendtemporal knowledge graphscale + sophisticated temporal retrieval
claude-mema zero-config Claude Code pluginlocal storeautomatic capture inside Claude Code, no setup

None of these is "better" in the abstract — they target different users. This project's wedge is file-ownership + multi-agent sharing + a compile-not-retrieve stance, with almost no moving parts. If you need scale, autonomy, or a polished SDK, one of the others is very likely the right call.

Install

git clone https://github.com/wuzishu3-web/agent-memory-vault.git
cd agent-memory-vault

# 1. Point an env var at where your vault will live (OUTSIDE this repo)
export AGENT_MEMORY_VAULT="$HOME/my-vault"

# 2. Scaffold a fresh vault from the template
python3 scripts/init_vault.py

# 3. Dependencies
pip install pyyaml          # required by extract_relations.py
# (embeddings/ingest also need an OpenAI-compatible embedding endpoint — see Config)

Add export AGENT_MEMORY_VAULT=... to your shell profile so every agent sees it.

As a Claude Code skill

Symlink or copy this repo into your skills directory and the bundled SKILL.md makes it invocable:

ln -s "$(pwd)" ~/.claude/skills/agent-memory-vault

Usage

# Start a session already oriented
python3 scripts/agent_memory_boot.py --agent claude-code --task "refactor the auth module"

# Write a durable note
python3 scripts/agent_memory.py --type decision --agent claude-code \
  --title "Why we switched to X" --summary "..." --body "..."

# Ingest an external source (see "the star" above)
python3 scripts/ingest.py --agent claude-code --title "..." --summary "..." --url "..." --source-type article

# Search
python3 scripts/query_vault.py "how did we handle rate limiting"

# Update the hot cache at the end of a session
python3 scripts/update_hot.py --agent claude-code --last "..." --active "..." --dont "..."

# Lint the vault
python3 scripts/vault_health_check.py

Configuration

Env varDefaultPurpose
AGENT_MEMORY_VAULT~/agent-memory-vaultPath to your vault.

Embedding endpoint (used by build_embeddings.py, query_vault.py, ingest.py) defaults to an OpenAI-compatible server at http://127.0.0.1:1234/v1/embeddings (e.g. LM Studio running text-embedding-nomic-embed-text-v1.5). Override with --url / --model. If the endpoint is down, ingest still writes pages — it just skips cross-references and re-indexing and marks the page for later indexing. Vectors are never a hard dependency for capturing knowledge.

Multi-agent setup

The whole point is that several agents share one vault. Each agent:

  1. runs agent_memory_boot.py --agent <name> at the start,
  2. writes durable facts via agent_memory.py / ingest.py,
  3. overwrites hot.md via update_hot.py at the end.

WRITE_GUIDE.md is the single authority that maps content → where it goes, so three agents don't each invent their own filing scheme. Add new agents by dropping a profile in 02_Agents/ and a key in AGENT_FILES (in agent_memory_boot.py / agent_memory.py).

中文简介

给 AI 编程 agent(Claude Code、Codex…)用的共享长期记忆 + 知识入库系统,底座是纯 Markdown / Obsidian 笔记库。

不再是传统 RAG 的"临时检索",而是把知识编译成持续维护的结构化页面,并自动完成最累的"记账"——交叉引用、去重、索引、一致性。核心亮点是 ingest.py 入库管道:把任意外部源变成一篇页面,自动双向连上语义最近的旧笔记 + 质量闸门(不达标的隔离进 Inbox,正式区永不出半成品)+ 增量重建索引。理念是"理解归 agent、记账归脚本",所以能全自动又不产生垃圾。灵感来自 Karpathy 的 LLM Wiki Pattern(知识表达层)与 GBrain(知识运行层),本项目把两层合一。

安装见上方 Install;用法见 Usage。

Credits

  • Andrej Karpathy — the LLM Wiki Pattern that frames the expression layer.
  • GBrain — the framing of a continuously-running knowledge runtime.

License

MIT © 2026 wuzishu3-web

Ver o original no GitHub

Bom para

Relacionados