From fbb6554ba5fb71d760ab8058d4500212ffe72a48 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 6 May 2026 13:31:26 +0000 Subject: [PATCH] docs: refresh public README --- README.md | 140 ++++++++++++++++++++++++++---------------------------- 1 file changed, 68 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index 8dbd1fc..c220ad2 100644 --- a/README.md +++ b/README.md @@ -1,89 +1,65 @@ -# agentic-lab +# Agentic Memory -Local-first agentic memory lab. A controlled note-capture pipeline built with Claude Code, n8n, and an Obsidian vault. +Agentic Memory is a local-first capture pipeline for landing structured notes and source material into an Obsidian-style inbox through Claude Code, n8n, and controlled scripts. -**The repo is the control plane. The vault is the data plane — never committed.** +## Current Status ---- +The repository is an early local lab for memory capture. It includes n8n workflow utilities, a Docker Compose setup for local n8n, a PowerShell send script, vision/runbook docs, and a strict rule that vault content stays local and out of Git. -## What It Does +The repo is the control plane. The vault is the data plane. -Captures notes (text and PDF) from any source and lands them in an Obsidian inbox with validated frontmatter. n8n handles the webhook intake; Claude Code enforces the capture contract; the vault stores the results locally. +## Key Capabilities -``` -Input (text / PDF) - │ - ▼ - n8n webhook / PowerShell script - │ - ▼ - vault/inbox/ ← structured note with YAML frontmatter - │ - ▼ - Obsidian (local, not committed) +- Text and PDF note capture into a vault inbox. +- YAML frontmatter contract for every captured note. +- Local n8n webhook intake through a Docker Compose service. +- Claude Code instructions for enforcing capture rules and safety boundaries. +- Runbook coverage for happy paths, edge cases, failure paths, and security checks. + +## Workflow + +```text +Text or PDF input + -> send script or n8n webhook + -> capture workflow + -> vault/inbox/ + -> Obsidian review ``` ---- +Every note starts in `vault/inbox/` with validated frontmatter before it is organized into notes, projects, or sources. -## Prerequisites +Useful docs: -| Tool | Purpose | -|------|---------| -| [Claude Code](https://claude.ai/code) | Orchestration and capture contract enforcement | -| [n8n](https://n8n.io) | Webhook intake and workflow automation | -| [Docker](https://docker.com) | Runs n8n locally | -| [Obsidian](https://obsidian.md) | Open `vault/` as your local vault | -| PowerShell | Send notes via `send_note.ps1` | +- [Vision](docs/00_vision.md) +- [Runbook](docs/02_runbook.md) +- [Claude Code Instructions](CLAUDE.md) ---- +## Quick Start -## Setup +Create the local n8n environment file. This repo intentionally ignores `n8n/.env`; fill it with local-only values such as `N8N_ENCRYPTION_KEY`, `WEBHOOK_URL`, and `N8N_RESTRICT_FILE_ACCESS_TO`. ```bash -# 1. Create the n8n environment file (never committed) -cp n8n/.env.example n8n/.env -# Fill in n8n webhook URL and any other required values - -# 2. Start n8n -cd n8n -docker compose up -d +touch n8n/.env +chmod 600 n8n/.env +``` -# 3. Test a capture -.\n8n\scripts\send\send_note.ps1 -Title "Test" -Body "Hello" -Tags "test" +Start local n8n: -# 4. Verify in Obsidian -# Note should appear in vault/inbox/ with valid YAML frontmatter +```bash +cd n8n +docker compose -f compose.yaml up -d ``` ---- - -## Repository Layout +Send a test note from PowerShell: -``` -agentic-lab/ -├── CLAUDE.md # Capture contract and safety rules -├── docs/ -│ ├── 00_vision.md # Goals and phase plan -│ └── 02_runbook.md # Tests, failure cases, security checklist -├── n8n/ -│ ├── docker-compose.yml # n8n container setup -│ ├── .env.example # Required env vars (copy to .env locally) -│ └── scripts/send/ -│ └── send_note.ps1 # Approved capture script -├── vault/ # Obsidian vault skeleton (content gitignored) -│ ├── inbox/ # All new notes land here -│ ├── notes/ -│ ├── projects/ -│ └── sources/ -└── examples/ # Sample notes and test payloads +```powershell +.\n8n\scripts\send\send_note.ps1 -Title "Test" -Body "Hello" -Tags "test" ``` ---- +Then verify the note appears under `vault/inbox/` with valid YAML frontmatter. ## Note Format -Every captured note gets YAML frontmatter: - ```yaml --- id: @@ -100,18 +76,38 @@ summary: "" --- ``` ---- +## Repository Layout + +```text +docs/ vision and runbook +n8n/ local n8n compose file and helper scripts +n8n/scripts/send/ approved note-send entrypoint +CLAUDE.md capture contract and operating rules +README.md public project overview +``` -## Safety Rules +## Verification -- `vault/**` is gitignored — no vault content is ever committed -- `n8n/.env` is gitignored — no secrets in tracked files -- New notes always land in `vault/inbox/` first -- Bulk moves and deletes require explicit confirmation +Recommended checks: ---- +```bash +git diff --check +cd n8n && docker compose -f compose.yaml config +``` + +Manual acceptance checks are documented in [`docs/02_runbook.md`](docs/02_runbook.md): a note capture is successful only when the Markdown and YAML are valid, the note is visible in Obsidian, no secrets are written, and no vault content is committed. + +## Privacy And Safety + +- `vault/**` content must stay local and uncommitted. +- `n8n/.env` must stay local and uncommitted. +- New notes always land in the inbox first. +- Bulk moves and deletes require explicit confirmation. +- Webhooks should not be exposed publicly until an explicit access layer exists. -## Docs +## Roadmap -- [docs/00_vision.md](docs/00_vision.md) — Goals and phase plan -- [docs/02_runbook.md](docs/02_runbook.md) — Runbook, tests, failure cases +- Keep the local capture path small and verifiable. +- Add repeatable fixture tests for frontmatter validation and failure cases. +- Harden webhook authentication before any remote capture mode. +- Build review and organization flows after inbox capture is reliable.