Hippocampus Knowledge Base

Core Rule

ALL markdown → hippocampus. No exceptions.

• •Never create .md files in project directories
• •Never create .md files in /tmp or elsewhere
• •Everything goes to ~/.claude/hippocampus/ (global or project tier)

Authority Model

• •AI autonomy: Search and present options (no approval needed)
• •User authority: Tier selection, phantom node choice, edit vs create
• •Pattern: AI finds, user classifies

Determine Intent

• •Finding resource? → Discovery path
• •Creating/editing markdown? → Create/Edit path
• •Adding binary files? (auto-detect: .png, .jpg, .pdf, .opus, .mp3, .mp4, etc.) → Binary Asset path

Discovery Path

Step 1: Search Hippocampus

• •Use Task tool with subagent_type=Explore to search hippocampus
• •Path: ~/.claude/hippocampus/
• •Search query based on user's request

Step 2: Present Paths for Selection

• •Show found file paths via AskUserQuestion with multiSelect: true
• •User selects which files to read
• •Only read selected files (saves context window)

Step 3: Return Content

• •Read only the user-selected files
• •Return relevant content to user

Create/Edit Path

Step 1: Search First

• •Use Task tool with subagent_type=Explore to search hippocampus
• •Path: ~/.claude/hippocampus/
• •Check if similar content already exists
• •If found: Present paths via AskUserQuestion → user picks to edit or create new
• •If not found: Continue to Step 2

Step 2: Tier Selection

AskUserQuestion with options:

• •Global (~/.claude/hippocampus/global/): Cross-project content (ADRs, patterns, business ops)
  • •Phantom nodes: Topic-based (e.g., [[docker-deployment]], [[prompt-engineering]])
• •Project (~/.claude/hippocampus/project/{name}/): Client-specific content
  • •Phantom nodes: Client-based (e.g., [[client-archibus]], [[client-iitr]])

Step 3: Phantom Node Selection

• •Use Explore agent to search for existing phantom nodes in hippocampus
• •Present found options to user via AskUserQuestion
• •User picks existing or creates new [[phantom-node]]
• •Convention: Use tier-appropriate phantom node type (topic-based for global, client-based for project)

Step 4: Publishing Decision

AskUserQuestion:

• •Publish to GitHub Pages?
• •Options: Yes / No
• •If Yes: Add publish: true to frontmatter
• •Result: File will be mirrored to public-wilsch-ai-pages repo on push
• •Return link: https://mariuswilsch.github.io/public-wilsch-ai-pages/{tier}/{filename} (without .md extension)

Step 5: Create File

• •Path: ~/.claude/hippocampus/{tier}/filename.md
• •Include selected phantom node wikilink on Line 2-3, after # Title
• •Use descriptive filename (no prefixes needed)

Step 6: Git Commit

• •Commit changes with descriptive message
• •Git tracks all document evolution

Binary Asset Path

For non-markdown files (images, PDFs, audio, video, etc.)

Step 1: Tier + Folder Selection

• •Same as Create/Edit path: Global or Project tier
• •Files go to: ~/.claude/hippocampus/{tier}/{folder}/

Step 2: Move Binary Files

• •Move files to selected hippocampus folder
• •Keep original filenames (or rename if requested)

Step 3: Create Minimal Index

Create index.md with: title, phantom node, then one line per file:

# {Descriptive Title}
[[phantom-node]]
![Image description](image.png)
[Document description](document.pdf)
[Audio description](audio.opus)

Format by file type:

• •Images: ![Description](file.png)
• •Documents: [Description](file.pdf)
• •Audio/Video: [Description](file.opus)

One index per folder. Add lines as files are added.

Step 4: Git Commit

• •Commit binary files + index.md together
• •Message: "feat: add {description} to hippocampus"