diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ad99e24 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,177 @@ +# LLM Wiki Agent — Schema & Workflow Instructions + +This wiki is maintained entirely by your coding agent. No API key or Python scripts needed — just open this repo in Codex, OpenCode, or any agent that reads this file, and talk to it. + +## How to Use + +Describe what you want in plain English: +- *"Ingest this file: raw/papers/my-paper.md"* +- *"What does the wiki say about transformer models?"* +- *"Check the wiki for orphan pages and contradictions"* +- *"Build the knowledge graph"* + +Or use shorthand triggers: +- `ingest ` → runs the Ingest Workflow +- `query: ` → runs the Query Workflow +- `lint` → runs the Lint Workflow +- `build graph` → runs the Graph Workflow + +--- + +## Directory Layout + +``` +raw/ # Immutable source documents — never modify these +wiki/ # Agent owns this layer entirely + index.md # Catalog of all pages — update on every ingest + log.md # Append-only chronological record + overview.md # Living synthesis across all sources + sources/ # One summary page per source document + entities/ # People, companies, projects, products + concepts/ # Ideas, frameworks, methods, theories + syntheses/ # Saved query answers +graph/ # Auto-generated graph data +tools/ # Optional standalone Python scripts (require ANTHROPIC_API_KEY) +``` + +--- + +## Page Format + +Every wiki page uses this frontmatter: + +```yaml +--- +title: "Page Title" +type: source | entity | concept | synthesis +tags: [] +sources: [] # list of source slugs that inform this page +last_updated: YYYY-MM-DD +--- +``` + +Use `[[PageName]]` wikilinks to link to other wiki pages. + +--- + +## Ingest Workflow + +Triggered by: *"ingest "* + +Steps (in order): +1. Read the source document fully +2. Read `wiki/index.md` and `wiki/overview.md` for current wiki context +3. Write `wiki/sources/.md` — use the source page format below +4. Update `wiki/index.md` — add entry under Sources section +5. Update `wiki/overview.md` — revise synthesis if warranted +6. Update/create entity pages for key people, companies, projects mentioned +7. Update/create concept pages for key ideas and frameworks discussed +8. Flag any contradictions with existing wiki content +9. Append to `wiki/log.md`: `## [YYYY-MM-DD] ingest | ` + +### Source Page Format + +```markdown +--- +title: "Source Title" +type: source +tags: [] +date: YYYY-MM-DD +source_file: raw/... +--- + +## Summary +2–4 sentence summary. + +## Key Claims +- Claim 1 +- Claim 2 + +## Key Quotes +> "Quote here" — context + +## Connections +- [[EntityName]] — how they relate +- [[ConceptName]] — how it connects + +## Contradictions +- Contradicts [[OtherPage]] on: ... +``` + +--- + +## Query Workflow + +Triggered by: *"query: <question>"* + +Steps: +1. Read `wiki/index.md` to identify relevant pages +2. Read those pages +3. Synthesize an answer with inline citations as `[[PageName]]` wikilinks +4. Ask the user if they want the answer filed as `wiki/syntheses/<slug>.md` + +--- + +## Lint Workflow + +Triggered by: *"lint"* + +Check for: +- **Orphan pages** — wiki pages with no inbound `[[links]]` from other pages +- **Broken links** — `[[WikiLinks]]` pointing to pages that don't exist +- **Contradictions** — claims that conflict across pages +- **Stale summaries** — pages not updated after newer sources +- **Missing entity pages** — entities mentioned in 3+ pages but lacking their own page +- **Data gaps** — questions the wiki can't answer; suggest new sources + +Output a lint report and ask if the user wants it saved to `wiki/lint-report.md`. + +--- + +## Graph Workflow + +Triggered by: *"build graph"* + +First try: `python tools/build_graph.py --open` + +If Python/deps unavailable, build manually: +1. Search for all `[[wikilinks]]` across wiki pages +2. Build nodes (one per page) and edges (one per link) +3. Infer implicit relationships not captured by wikilinks — tag `INFERRED` with confidence score; low confidence → `AMBIGUOUS` +4. Write `graph/graph.json` with `{nodes, edges, built: date}` +5. Write `graph/graph.html` as a self-contained vis.js visualization + +--- + +## Naming Conventions + +- Source slugs: `kebab-case` matching source filename +- Entity pages: `TitleCase.md` (e.g. `OpenAI.md`, `SamAltman.md`) +- Concept pages: `TitleCase.md` (e.g. `ReinforcementLearning.md`, `RAG.md`) + +## Index Format + +```markdown +# Wiki Index + +## Overview +- [Overview](overview.md) — living synthesis + +## Sources +- [Source Title](sources/slug.md) — one-line summary + +## Entities +- [Entity Name](entities/EntityName.md) — one-line description + +## Concepts +- [Concept Name](concepts/ConceptName.md) — one-line description + +## Syntheses +- [Analysis Title](syntheses/slug.md) — what question it answers +``` + +## Log Format + +`## [YYYY-MM-DD] <operation> | <title>` + +Operations: `ingest`, `query`, `lint`, `graph` diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..d15336b --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,133 @@ +# LLM Wiki Agent — Schema & Workflow Instructions + +This wiki is maintained entirely by Gemini CLI. No API key or Python scripts needed — just open this repo with `gemini` and talk to it. + +## How to Use + +Describe what you want in plain English: +- *"Ingest this file: raw/papers/my-paper.md"* +- *"What does the wiki say about transformer models?"* +- *"Check the wiki for orphan pages and contradictions"* +- *"Build the knowledge graph"* + +Or use shorthand triggers: +- `ingest <file>` → runs the Ingest Workflow +- `query: <question>` → runs the Query Workflow +- `lint` → runs the Lint Workflow +- `build graph` → runs the Graph Workflow + +--- + +## Directory Layout + +``` +raw/ # Immutable source documents — never modify these +wiki/ # Agent owns this layer entirely + index.md # Catalog of all pages — update on every ingest + log.md # Append-only chronological record + overview.md # Living synthesis across all sources + sources/ # One summary page per source document + entities/ # People, companies, projects, products + concepts/ # Ideas, frameworks, methods, theories + syntheses/ # Saved query answers +graph/ # Auto-generated graph data +tools/ # Optional standalone Python scripts +``` + +--- + +## Page Format + +Every wiki page uses this frontmatter: + +```yaml +--- +title: "Page Title" +type: source | entity | concept | synthesis +tags: [] +sources: [] +last_updated: YYYY-MM-DD +--- +``` + +Use `[[PageName]]` wikilinks to link to other wiki pages. + +--- + +## Ingest Workflow + +Triggered by: *"ingest <file>"* + +1. Read the source document fully +2. Read `wiki/index.md` and `wiki/overview.md` for current wiki context +3. Write `wiki/sources/<slug>.md` (source page format below) +4. Update `wiki/index.md` — add entry under Sources +5. Update `wiki/overview.md` — revise synthesis if warranted +6. Update/create entity and concept pages +7. Flag contradictions with existing wiki content +8. Append to `wiki/log.md`: `## [YYYY-MM-DD] ingest | <Title>` + +### Source Page Format + +```markdown +--- +title: "Source Title" +type: source +tags: [] +date: YYYY-MM-DD +source_file: raw/... +--- + +## Summary +2–4 sentence summary. + +## Key Claims +- Claim 1 + +## Key Quotes +> "Quote here" + +## Connections +- [[EntityName]] — how they relate + +## Contradictions +- Contradicts [[OtherPage]] on: ... +``` + +--- + +## Query Workflow + +Triggered by: *"query: <question>"* + +1. Read `wiki/index.md` — identify relevant pages +2. Read those pages +3. Synthesize answer with `[[PageName]]` citations +4. Offer to save as `wiki/syntheses/<slug>.md` + +--- + +## Lint Workflow + +Triggered by: *"lint"* + +Check for: orphan pages, broken links, contradictions, stale content, missing entity pages, data gaps. + +--- + +## Graph Workflow + +Triggered by: *"build graph"* + +Try `python tools/build_graph.py --open` first. If unavailable, build graph.json and graph.html manually from wikilinks. + +--- + +## Naming Conventions + +- Source slugs: `kebab-case` +- Entity/Concept pages: `TitleCase.md` + +## Log Format + +`## [YYYY-MM-DD] <operation> | <title>` diff --git a/README.md b/README.md index 0f74f85..b93058f 100644 --- a/README.md +++ b/README.md @@ -20,30 +20,43 @@ Three layers: - **`wiki/`** — Claude-maintained markdown pages (Claude writes, you read) - **`graph/`** — auto-generated knowledge graph visualization -## Quick Start — Claude Code (no API key needed) +## Quick Start — Any Coding Agent (no API key needed) -Open this repo in [Claude Code](https://claude.ai/code): +Works with Claude Code, Codex, OpenCode, Gemini CLI, and any agent that reads a config file from the repo root. + +| Agent | Config file read automatically | +|---|---| +| [Claude Code](https://claude.ai/code) | `CLAUDE.md` + `.claude/commands/` | +| [OpenAI Codex](https://openai.com/codex) | `AGENTS.md` | +| OpenCode / Pear AI | `AGENTS.md` | +| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `GEMINI.md` | +| Any other agent | Point it at `AGENTS.md` or `README.md` | ```bash git clone https://github.com/SamurAIGPT/GPT-Agent.git cd GPT-Agent -claude # opens Claude Code in this repo + +claude # Claude Code +codex # OpenAI Codex +opencode # OpenCode +gemini # Gemini CLI ``` -Claude Code reads `CLAUDE.md` automatically. Then just talk to it: +Each agent reads its config file and follows the same workflows. Then talk to it: ``` -# Drop a source into raw/ first, then: +# Claude Code slash commands: /wiki-ingest raw/articles/my-article.md - /wiki-query what are the main themes across all sources? - /wiki-lint - /wiki-graph -``` -Or in plain English: *"Ingest this paper"*, *"What does the wiki say about X?"*, *"Check for contradictions"* +# Any agent (plain English): +"Ingest this paper: raw/papers/my-paper.md" +"What does the wiki say about X?" +"Check for contradictions" +"Build the knowledge graph" +``` ## Quick Start — Standalone Python (requires API key)