@nfinitmonkeys/brain

Persistent, compounding memory for clans. A markdown vault on disk is the source of truth; LLM-driven operations (ingest, query, lint, save, fold) compound knowledge over time. Pluggable LLM backends — Cortex by default, any OpenAI-compatible LLM as configured.

Status: 0.1.x — early. The vault format is committed (claude-obsidian compatible). The library API may evolve; the on-disk format will not.

Why

A clan without persistent memory is a goldfish. Every session starts fresh; the LLM has no continuity of self; goals don't accumulate; decisions don't build taste. This package gives clans real memory:

• A markdown vault at <clan>/.brain/wiki/ — the persistent artifact, version-controlled with code
• A library that operates on it from any Node runtime — Council Alpha runtimes (Fargate), CLI sessions, scheduled jobs, webhook handlers, Wild clans (no Jungle attached)
• Pluggable LLM — Cortex (default for Nfinit Monkeys clans), or OpenAI / Anthropic / Ollama / anything OpenAI-compatible

The vault format is intentionally compatible with claude-obsidian (MIT, Daniel Agrici) so its Claude Code plugin (/wiki, /save, /wiki-query, /wiki-lint slash commands) works against the same vault when you're in a CLI session. The library is what makes the same operations work from anywhere else.

Install

npm install @nfinitmonkeys/brain

Quick start

import { Brain } from '@nfinitmonkeys/brain';
import { CortexLLM } from '@nfinitmonkeys/llm-cortex';  // separate package, optional

const brain = new Brain({
  vaultRoot: '~/Projects/my-clan/.brain',
  llm: new CortexLLM({
    apiKey: process.env.CORTEX_API_KEY!,
    baseUrl: 'https://cortexapi.nfinitmonkeys.com/v1',
    model: 'qwen2.5-72b-awq',
  }),
});

// Read continuity at session start
const context = await brain.bootSession();
console.log(context.hot);  // wiki/hot.md content

// Append an observation (no LLM call — pure file I/O)
await brain.appendObservation('Self-message rate dropped to 0/min after Phase 0 deploy');

// Record a decision (no LLM call)
await brain.recordDecision({
  topic: 'phase-0-cleanup',
  verdict: 'approved',
  approver: 'Bill Jobes',
  rationale: '...',
});

// Propose a candidate goal (no LLM call — Alpha drafts, human approves later)
const goalId = await brain.proposeCandidateGoal({
  name: 'Audit DocumentDB clusters for idle clusters',
  anchor: '~/Projects/jungle/.brain/wiki/observations/2026-05-03',
  capabilityTag: 'infrastructure',
});

// Ingest a source (LLM-driven — extracts entities/concepts, updates index)
await brain.ingest({
  source: { type: 'text', text: '...long document...' },
  tags: ['phase-0', 'aws-audit'],
});

// Query (LLM-driven — reads index, drills into pages, cites sources)
const answer = await brain.query('what was the EV market hallucination root cause?');
console.log(answer.text);
console.log(answer.citations);  // ['wiki/observations/2026-05-03', ...]

// Update continuity at session end
await brain.closeSession({ summary: 'Phase 0 shipped, brain initialized, Forge briefed' });

Vault layout

<clan>/.brain/
├── CLAUDE.md                     identifies vault, documents schema
├── .raw/                         immutable source documents (agents read, never write)
├── _templates/                   Obsidian Templater templates (optional)
├── .vault-meta/                  vault metadata (address counter, lint thresholds)
├── .obsidian/                    Obsidian.md app config (optional, for visual graph view)
└── wiki/                         agent-owned knowledge
    ├── hot.md                    session continuity (read at start, written at end)
    ├── identity.md               who this clan is
    ├── index.md                  top-level navigation
    ├── log.md                    chronological action log (append-only)
    ├── overview.md               clan's mission statement
    ├── entities/                 people, orgs, products, repos
    ├── concepts/                 ideas, patterns, frameworks
    ├── sources/                  annotated source pointers
    ├── questions/                open questions / FAQs
    ├── comparisons/              side-by-side analyses
    ├── canvases/                 Obsidian canvas files
    ├── folds/                    log rollups (DragonScale, optional)
    ├── meta/                     dashboards, lint reports
    ─── clan-specific extensions ───
    ├── goals/{standing,active,candidates,retired}/
    ├── observations/<YYYY-MM-DD>.md
    ├── decisions/<YYYY-MM-DD>-<topic>.md
    └── relationships/{humans,alphas}/<name>.md

LLM backend abstraction

The library's LLM interface has one required method (chat) and several optional ones (embed, structuredExtract, summarize, iris, vlm, tts, stt). Adapters implement what the underlying LLM supports natively; the Brain library falls back to chat-based composition for the rest.

interface LLM {
  // Required
  chat(messages: Message[], opts?: ChatOpts): Promise<ChatResponse>;

  // Optional — implement when native support exists
  embed?(text: string | string[]): Promise<number[][]>;
  structuredExtract?<T>(text: string, schema: JSONSchema): Promise<T>;
  summarize?(text: string, targetWords?: number): Promise<string>;

  // Cortex-specific (optional)
  iris?(doc: Buffer | string): Promise<StructuredDoc>;
  vlm?(image: Buffer | URL, prompt: string): Promise<string>;
  tts?(text: string): Promise<Buffer>;
  stt?(audio: Buffer): Promise<string>;
}

Cortex (Nfinit Monkeys' LLM gateway) is the richest backend — native embeddings (BGE-M3 1024-dim), Iris for structured document parsing, VLM/TTS/STT for multimedia. Other backends gracefully degrade.

CLI

# Initialize a brain in the current directory (reads clan registration if available)
npx clan-brain init

License

MIT.