MEMEX

Keep the knowledge. Keep the reasoning.

Associative memory for AI agents, stored in Markdown you own.

Getting started · Design · Report a bug

Contents

• About the project
• Getting started
• Usage
• Agent integration
• Project status
• Contributing
• License and acknowledgments

About the project

An agent can finish a task and lose the context that made its decisions sensible. MEMEX keeps a durable record of findings, corrections, and the reasons one piece of knowledge led to another. A later session can retrieve the evidence and follow the reasoning without reconstructing an entire conversation.

The Library consists of Books: Markdown files with YAML frontmatter. A link connects related Books. A trail orders those connections and records why each step follows. One Book can belong to several trails.

Qualifying findings are recorded during the live turn under an explicit selection rule. Creating or changing a trail requires human approval. The files remain the authoritative record; the search index can be rebuilt.

Built with Python 3.11+, PyYAML, and POSIX file locking. Optional semantic search uses local Ollama embeddings. The command-line workflow needs no database or running application server.

Getting started

Use Linux with Python 3.11+ and virtual-environment support. This repository includes a fictional greenhouse Library so you can try the workflow immediately. All measurements in that example are illustrative.

git clone https://github.com/appendix0/Memex.git
cd Memex
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt

export PATH="$PWD/bin:$PATH"
export MEMEX_TZ=UTC  # change to your IANA timezone

memex recall "why does the controller use a median"
memex trail building-the-greenhouse

Recall works without Ollama and explicitly reports when it uses lexical search. For semantic recall, install and start Ollama, then run:

ollama pull bge-m3
memex reindex
memex doctor

doctor checks schema, links, index freshness, missing embeddings, and duplicate trail steps. Missing embeddings produce a failing diagnostic even though lexical recall remains available.

For your own Library, use a separate local checkout and remove its Git remote before recording personal information (git remote remove origin). Keep brain/CLASSIFICATION.md, brain/RESOLVER.md, and brain/schema.md when replacing the fictional Books. Adapt the controlled topic vocabulary and AGENTS.md to your work. Keep code contributions in a separate public checkout.

Usage

Retrieve the record

memex recall "watering decision" --full
memex recall "watering decision" --json
memex trail --through projects/greenhouse

Read the referenced Book before relying on a search excerpt. New and changed Books are searchable lexically immediately; memex reindex refreshes their semantic vectors.

Record a finding

Automatic recording requires a trigger from memex/criterion.py, inspectable evidence, and the future question the record answers. The six triggers cover user decisions, measurements, established causes, sources that changed a decision, capability changes, and contradictions of existing claims.

For an explicit request to remember something, use manual input:

memex note projects/greenhouse \
  "Keep watering decisions traceable to the sensor reading." \
  --manual --agent codex

recorded, manual, and agreed distinguish automatic capture, user-directed input, and exact human assent. They describe provenance; they do not certify truth. Corrections preserve the previous claim in history. Research records are append-only. See the writing skill for automatic records, new Books, and corrections.

Keep the reasoning

The example trail connects the greenhouse project, a sensor trial, a report, and a host configuration Book. Its first two steps explain the design:

A greenhouse needs a decision, not a clock.
  → projects/greenhouse
  ↓ A single transient reading can trigger the pump.
So the decision needed a measurement it could not be fooled by.
  → research/germination-trial

This is a shortened illustration; the trail file contains the full route and reasons. Order follows the argument, so dates need not be chronological. A reason must come from the record, not be invented by the agent.

memex daily refreshes the index and proposes trail steps supported by existing prose. It makes no generative-model call. Review them with memex pending; accept a step with memex pending --accept ID --agreed only after approving its exact route and reason. Running the command does not install a schedule.

Agent integration

The CLI supports live recording by Claude and Codex. AGENTS.md and the writing skill carry the shared contract. Run memex start at session start if your harness does not inject it.

Optional hook examples connect session start, session end, and turn end. Adapt their paths and scope before enabling them. The Scribe is optional catch-up extraction from Claude Code transcripts; it uses the installed claude CLI and can incur model usage. It may append qualifying records to existing Books, but cannot create Books, replace claims, change trails, or claim approval. See Scribe setup and limits.

Dispatch provides local correspondence between agents:

dispatch inbox --agent codex

Messages, acknowledgments, and artifact references remain outside the Library. A message does not grant permission or become a fact. See Dispatch.

Project status

The current implementation includes guarded recording, hybrid recall, trail navigation, bounded Scribe extraction, local Dispatch, and consistent snapshots. It is a CLI project with a worked example, not a hosted service.

Current limits:

• Privacy depends on the workflow. vault labels and CLI checks are not an operating-system sandbox. Hosted agents see retrieved context. See the access policy.
• Session context has no fixed size cap. Preferences and hot-state files can grow even though knowledge retrieval happens on demand.
• No automatic multimodal ingestion or external connectors. PDFs, images, spreadsheets, and source connectors are a design direction.
• Backups need configuration. memex-snapshot prepares a local snapshot; encryption, remote storage, and scheduling are your responsibility.

The command reference covers the CLI; the design document explains the implementation and remaining work. Use issues for bugs and proposals.

Contributing

Keep changes focused, include reproduction steps for bugs, and use synthetic fixtures. Run both suites before opening a pull request:

python3 tests/test_memex.py
python3 -m unittest discover -s tests -p 'test_*.py'

Tests use temporary Libraries and mock generative-model calls. Include the commands and results in your pull request. Keep personal Books, transcripts, credentials, and runtime state out of contributions.

License and acknowledgments

MIT.

Inspired by Vannevar Bush's As We May Think (1945); the source Book connects the essay to the design. README structure adapted from Best-README-Template.