reefiki 0.2.2

Multi-project markdown wiki and memory control plane for LLM agents.

REEFIKI

AI agents are fast, but they are bad at remembering project context: decisions stay buried in chats, useful procedures disappear, and the next agent starts from zero again.

REEFIKI solves that problem as a local wiki memory for AI agents: it keeps only the knowledge that is likely to be useful again, not the whole session noise.

Русский · 中文 · Quick Start · Commands

About this repository. This is the public REEFIKI product. Development happens in a separate private contour; filtered snapshots are published here — so the public history is short and intentionally trails by one snapshot cycle. What is included, what is excluded, and how it is refreshed: see docs/SNAPSHOT.md.

Trust map. Canonical source: github.com/NeAGI/Reefiki. PyPI package: pypi.org/project/reefiki. To verify a release, compare the commit SHA in the PyPI Trusted Publishing provenance against a tag in this repository — they must match. From 0.2.1 onward the provenance publisher is NeAGI/Reefiki, matching the canonical source. Older releases (0.1.1–0.2.0) were published under the legacy kisslex2013-alt/Reefiki identity; their historical provenance still shows that publisher against the same commits, which is expected.

---

The Problem

AI-agent work often breaks not because of code, but because of memory.

After a few threads, the same issues appear:

• an important decision is stuck in a chat and cannot be found;
• a new agent does not know why the project is shaped this way;
• a useful trick was discovered once but never became a reusable skill;
• links, notes, and conclusions get mixed with drafts and noise;
• agent memory becomes either too short or too dirty.

A normal note-taking system does not fully solve this either: it is easy to save everything, but hard to separate reusable knowledge from accidental context.

What REEFIKI Is

REEFIKI is a local multi-project distillation wiki for AI agents.

In practice:

• every project has its own wiki;
• the agent saves decisions, skills, conclusions, and sources there;
• weak or temporary material is deferred instead of polluting the base;
• everything is stored as markdown files with git history;
• workflow rules live in AGENTS.md, so different agents can follow them.

REEFIKI is not another chatbot, cloud memory service, or archive of every message. It is a filter that turns working chaos into short, verifiable, portable project memory.

Why REEFIKI

The space of memory tools is filling up, and "markdown memory" on its own is no longer a differentiator. Different jobs call for different tools; here is where REEFIKI differs by design.

• A filter, not a warehouse. REEFIKI does not index everything: material goes through distillation — inbox → selection → types (decisions, skills, concepts, sources). What stays is reusable knowledge, not a full log.
• Memory is human-readable and lives in git. Everything is stored as markdown under version control: you can read it, review it in a PR, roll it back. There is no hidden vector index as the single source of truth.
• Zero infrastructure. All you need is files and git — no vector DB, server, or cloud. Portability across agents comes through AGENTS.md: any agent that reads files can follow the rules.

	REEFIKI	Mem0 / OpenMemory	memsearch	Letta / Zep
Storage	Markdown + git, human-readable	Vectors/graph + dashboard	Markdown + vector DB (Milvus)	Inside a framework runtime / service
Knowledge selection	Distillation: inbox → filter → types	Automatic fact extraction	Index everything	Auto-extraction / temporal graph
Dependencies	None (files + git)	Server/cloud	Vector DB	Framework (LangGraph/Letta) / service
Portability across agents	AGENTS.md — any file-reading agent	Via MCP clients	Claude Code / Codex	Inside its own runtime
Governance / auditability	Health/lint, journal, git history, public/private layers	Dashboard	—	—

About the tools compared: Mem0/OpenMemory — memory via vectors/graph and MCP; memsearch — markdown + vector search (Milvus) for Claude Code/Codex; Letta — memory inside an agent framework; Zep — memory on a temporal knowledge graph. This compares tools by design, without benchmarks.

Project Profiles

Not every REEFIKI project is the same. When creating or connecting a project, you can tell the agent which profile it is:

Profile	Use for	Examples
agent_surface	rules, skills, adapters, diagnostics, and recovery for agent/IDE/runtime environments	Codex, Claude Code, Gemini, Mimo, Hermes
product	product decisions, delivery evidence, UX, and release knowledge	Metrica
knowledge_domain	topic/domain knowledge without a primary runtime layer	Suno, Instagram, Security Guidance
reefiki_core	REEFIKI rules and governance	reefiki

This is a manual onboarding label, not a required schema field. Details: docs/PROJECT_PROFILES.md.

Why It Exists

REEFIKI is useful when you work with AI agents regularly and want them to:

• continue with awareness of past decisions;
• avoid repeating mistakes that were already solved;
• recover project context quickly;
• save procedures as reusable skills;
• separate private memory from public material;
• hand work off between Codex, Claude Code, Cursor, Windsurf, and other agents.

The core idea: an agent should not only finish a task, but also leave a reusable trace behind.

How It Works

REEFIKI follows a simple cycle:

1. Capture: a link, file, decision, or conclusion enters the project inbox.
2. Filter: the agent checks whether it can be applied again.
3. Save: useful material becomes a wiki page, skill, decision, or synthesis.
4. Link: pages get links, an index entry, and a log record.
5. Recall later: the next agent answers from the accumulated wiki, not from guesses.

REEFIKI uses a few durable memory types (frontmatter type / validator ALLOWED_TYPES):

Type	What it stores
source	where an idea or material came from
entity	a stable thing in the world (tool, product, person, system)
concept	reusable understanding
decision	a decision and its reason
skill	a reproducible procedure
synthesis	conclusions from a session or project stage
antipattern	negative knowledge: what was tried and why it fails (time-boxed via recheck_after)

Rifiki

Rifiki is a small reef crab archivist: a keeper of the reef wiki who does not drag every grain of sand into memory, but selects the useful shells. In the README, Rifiki is a metaphor: session noise on the left, distillation in the center, clean project memory on the right.

Quick Start

Shortest trial without installing permanently:

pipx run reefiki first-run

Permanent install:

pipx install reefiki
reefiki first-run

first-run creates or reuses ~/reefiki-workspace, runs a health check, and shows 1-2 next actions.

Details: QUICKSTART.md and docs/INSTALL.md.

Working After Setup

After the first run, work with plain phrases:

You say	The agent does
"put this in the inbox"	saves material for later processing
"process the inbox"	turns useful material into wiki pages
"remember this as a decision"	saves a durable decision
"save this as a skill"	records a reusable procedure
"connect this project to the wiki"	creates a separate wiki and bridge only after explicit confirmation
"what did we decide about sync?"	answers only from the accumulated wiki
"capture the session conclusions"	saves a synthesis

What It Can Do Today

• Separate wiki projects under projects/<name>/.
• Connect an existing code project through _wiki.
• Capture -> process -> query -> harvest workflow.
• Agent-agnostic rules through AGENTS.md.
• Manual project profiles for agent/runtime, product, and knowledge-domain projects.
• Local markdown files instead of closed cloud storage.
• Wiki log and index.
• Health/lint checks to keep the base from becoming a dump.
• Handoff context for the next agent.
• Clear boundaries between local/private memory and material that can be shared publicly.

Full capability map: COMMANDS.md.

What REEFIKI Is Not

REEFIKI is intentionally not:

• a storage system for every chat message;
• a replacement for git, Obsidian, or an issue tracker;
• an automatic cloud sync service;
• a vector database "just in case";
• a system that writes anywhere without project boundaries.

If material cannot be applied again, it should not become durable wiki memory.

Safety

REEFIKI is local-first by default:

• user wiki projects stay local;
• raw/ is treated as an immutable archive;
• secrets, binaries, and oversized files are not saved automatically;
• public material is separated from local wiki projects and checked before publishing;
• the agent changes only explicitly selected project files.

In short: REEFIKI makes memory useful without blurring project boundaries.

For Agents

Agents do not need to remember internal commands. They read AGENTS.md and follow the project contract:

• from the REEFIKI root, they can create and connect projects;
• inside projects/<name>/, they can save and process knowledge;
• old wiki/log.md entries are never rewritten;
• raw/ is not edited;
• all durable writes must be explainable and reproducible.

That makes REEFIKI portable across Codex, Claude Code, Cursor, Windsurf/Cascade, Cline, and other LLM agents.

If a project is an agent/IDE/runtime environment such as Codex, Claude Code, Gemini, Mimo, or Hermes, treat it as an agent_surface: preserve portable procedures, adapters, diagnostics, and recovery notes, but do not merge wikis or copy skills automatically.

Token Economy

REEFIKI reduces token waste not by magically compressing everything, but by making the agent read less junk.

• Instead of the whole chat, the agent recalls short decisions, skills, concepts, and synthesis pages.
• Projects are isolated, so unrelated context does not leak into the current task.
• wiki/index.md and the log help find relevant pages without rereading the whole base.
• The handoff pack builds a bounded context bundle for the next agent.
• Weak material stays in the inbox or refusal path instead of becoming permanent memory.

Rule of thumb, not a guarantee: one short decision or skill page is often around 500-2,000 tokens and can replace 5,000-30,000 tokens of old chat context. A practical handoff pack usually stays around 2,000-8,000 tokens instead of tens of thousands of history tokens.

On repeat tasks, this often means roughly 50-90% fewer context-reading tokens; for returning to one decision or skill, the reduction can be 70-95%.

Details: docs/TOKEN_ECONOMY.md#english.

Next

• QUICKSTART.md: first run without knowing the CLI.
• COMMANDS.md: all REEFIKI operations.
• docs/TOKEN_ECONOMY.md: how REEFIKI saves tokens.
• docs/INSTALL.md: CLI install and smoke test.
• docs/obsidian-setup.md: safe Obsidian setup.
• docs/PUBLIC_DEMO.md: public demo and boundaries.
• docs/RECOVERY.md: recovery after failures.

Public roadmap: docs/PUBLIC_ROADMAP.md. Public backlog: docs/PUBLIC_BACKLOG.md.

Documentation status map: docs/STATUS.md.

License

REEFIKI code is distributed under Apache License 2.0. See LICENSE.

Wiki-project content belongs to the user who created or added it.

Acknowledgements and design influences

REEFIKI is an independent implementation. The materials and tools below are not imported as REEFIKI codebases and are not copied source code. They influenced the product as ideas, vocabulary, architecture patterns, and operating constraints.

• Karpathy's LLM Wiki gist: the idea of a compact, agent-readable wiki instead of repeatedly replaying chat history; distillation over raw archiving.
• REEF protocol: the capture -> distillation -> telemetry loop; cheap capture, deliberate processing, and later reuse as separate stages.
• Vannevar Bush's "As We May Think": Memex, associative trails, durable personal memory, and connected knowledge instead of isolated notes.
• Markdown wiki and Obsidian-style workflows: local markdown files, wikilinks, graph/viewer thinking, and readable knowledge without a cloud service. REEFIKI is not an Obsidian clone: its source of truth stays in the repository and agent-aware rules.
• Git worktree workflow: isolated task work, reviewable changes, and careful separation between local/private content and the public snapshot.
• memoir: short working memory and preferences as a separate layer. In REEFIKI it is an optional short-memory provider; durable truth remains in the markdown wiki.
• Graphify and graph-based retrieval: a graph of code, files, and documents as a navigation and candidate-selection layer. REEFIKI does not become a graph database; it uses graph ideas for relationships and compact context.
• CodeGraph-style navigation: disposable impact/callgraph/relationship queries over code as a developer aid, not as durable memory.
• Agent/IDE runtimes: Codex, Claude Code, Cursor, Windsurf/Cascade, Cline, Gemini, Mimo, and Hermes influenced the vendor-neutral AGENTS.md, project profiles, portable rules, and reusable runbooks.
• Local-first security practice: explicit project boundaries, public-material checks, append-only logs, immutable raw/, and avoiding broad save-everything behavior as REEFIKI-specific safety infrastructure.

The practical goal of REEFIKI is to combine wiki, agent workflow, short memory, graph navigation, and Git discipline into one local-first process where knowledge can be verified, transferred, and published safely.