Features

• Agent loop — tool calling, sub-agent delegation, doom-loop detection, context guard
• OpenAI-compatible — works with any /chat/completions endpoint (OpenAI, Anthropic, Ollama, etc.)
• File-based memory — keyword recall, zero vector DB dependency. Beats Letta/MemGPT on LoCoMo (86% vs 74%)
• Context compaction — automatic fact extraction + LLM summarization when context overflows
• Lifecycle hooks — before_prompt, before_tool, after_tool, agent_end
• Skills — installable SKILL.md extensions with ClawHub (pure JS git clone)
• Channels — Telegram, Cloud IM adapters (auto-detected from env)
• HTTP + WebSocket gateway — zero external dependencies, real-time streaming
• CLI — lumin agent, lumin serve, lumin health
• ~4,900 LOC — single production dependency (Zod)

Quick Start

Install

npm install @prismer/agent-core

Programmatic

import { runAgent } from '@prismer/agent-core';

process.env.OPENAI_API_KEY = 'sk-...';

await runAgent({
  type: 'message',
  content: 'What is 2 + 2?',
});

CLI

# Run agent with a message
lumin agent --message "Hello, world!"

# Start HTTP + WebSocket gateway
lumin serve --port 3001

# Health check
lumin health

WebSocket

const ws = new WebSocket('ws://localhost:3001/v1/stream');

ws.onopen = () => {
  ws.send(JSON.stringify({ type: 'chat.send', content: 'Hello!' }));
};

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type === 'text.delta') process.stdout.write(msg.delta);
  if (msg.type === 'chat.final') console.log('\n---\nDone:', msg.toolsUsed);
};

HTTP

# Chat (synchronous)
curl -X POST http://localhost:3001/v1/chat \
  -H 'Content-Type: application/json' \
  -d '{"content": "List files in the workspace"}'

# List tools
curl http://localhost:3001/v1/tools

# Health
curl http://localhost:3001/health

Configuration

All settings via environment variables. Sensible defaults for standalone use.

| Variable | Description | Default | |----------|-------------|---------| | OPENAI_API_KEY | LLM provider API key | (required) | | OPENAI_API_BASE_URL | LLM provider base URL | https://api.openai.com/v1 | | AGENT_DEFAULT_MODEL | Default model ID | gpt-4o | | WORKSPACE_DIR | Working directory | ./workspace | | LUMIN_PORT | HTTP/WS server port | 3001 | | MAX_CONTEXT_CHARS | Compaction threshold (chars) | 600000 | | MODEL_FALLBACK_CHAIN | Fallback models (comma-separated) | — | | PRISMER_PLUGIN_PATH | Path to workspace plugin | — | | TELEGRAM_BOT_TOKEN | Telegram channel (optional) | — | | LOG_LEVEL | debug / info / warn / error | info |

Custom Tools

import { createTool } from '@prismer/agent-core';
import { ToolRegistry } from '@prismer/agent-core/tools';

const tools = new ToolRegistry();

tools.register(createTool(
  'weather',
  'Get current weather for a city',
  {
    type: 'object',
    properties: {
      city: { type: 'string', description: 'City name' },
    },
    required: ['city'],
  },
  async (args) => {
    const res = await fetch(`https://wttr.in/${args.city}?format=j1`);
    return JSON.stringify(await res.json());
  },
));

Architecture

@prismer/agent-core
├── Core
│   ├── PrismerAgent             — agent loop + tool execution + doom-loop detection
│   ├── OpenAICompatibleProvider — LLM client (any /chat/completions endpoint)
│   ├── FallbackProvider         — automatic model fallback chain
│   ├── ToolRegistry             — tool registration + JSON Schema specs
│   └── EventBus                 — SSE / WebSocket event streaming
├── Memory
│   ├── MemoryStore (facade)     — store / recall / search / recent
│   └── FileMemoryBackend        — keyword-based, zero-dependency
├── Infrastructure
│   ├── HTTP + WebSocket server  — zero external deps (pure node:http)
│   ├── CLI                      — agent / serve / health commands
│   ├── SessionStore             — session management + compaction state
│   └── Config                   — Zod-validated, env var override
└── Extensions
    ├── HookRegistry             — before_prompt, before_tool, after_tool, agent_end
    ├── SkillLoader              — SKILL.md + YAML frontmatter
    ├── AgentRegistry            — sub-agent delegation via @mention
    └── ChannelManager           — Telegram, Cloud IM adapters

Subpath Exports

import { PrismerAgent } from '@prismer/agent-core/agent';
import { OpenAICompatibleProvider } from '@prismer/agent-core/provider';
import { ToolRegistry } from '@prismer/agent-core/tools';
import { SessionStore } from '@prismer/agent-core/session';
import { MemoryStore, FileMemoryBackend } from '@prismer/agent-core/memory';
import { HookRegistry } from '@prismer/agent-core/hooks';
import { EventBus } from '@prismer/agent-core/sse';
import { loadConfig } from '@prismer/agent-core/config';
import { createLogger } from '@prismer/agent-core/log';
import { VERSION } from '@prismer/agent-core';

Memory System

Zero-dependency file-based memory with keyword recall. Tested on the LoCoMo long-term conversation memory benchmark:

| Model | Overall | No Adversarial | vs Letta/MemGPT | |-------|---------|---------------|-----------------| | Claude Opus 4.6 | 86% | 95% | +12pp | | Kimi K2.5 | 63% | 56% | -11pp | | Letta/MemGPT | ~74% | — | baseline |

Zero-dependency keyword search + strong LLM outperforms Letta's embedding+rerank pipeline.

import { MemoryStore } from '@prismer/agent-core/memory';

const memory = new MemoryStore('./workspace');
await memory.store('The calibration coefficient is 0.03847', ['numeric']);
const results = await memory.search('calibration coefficient');
console.log(results); // [{ content: '...', score: 1.0, tags: ['numeric'] }]

Workspace Templates

Drop markdown files into your workspace to customize agent behavior:

| File | Priority | Purpose | |------|----------|---------| | IDENTITY.md / SOUL.md | 10 | Agent identity and persona | | AGENTS.md | 9 | Sub-agent routing and priorities | | TOOLS.md | 8 | Tool reference documentation | | USER.md | 3.5 | User preferences and context |

Skills

Install agent skills from git repositories:

# Via agent tool call
clawhub install research-paper
clawhub install https://github.com/user/my-skill.git
clawhub list
clawhub search "data analysis"

Each skill is a directory with a SKILL.md file (YAML frontmatter + markdown body) that gets injected into the system prompt.

API Reference

See docs/API.md for the complete HTTP, WebSocket, and IPC protocol documentation.

Contributing

git clone https://github.com/prismer-ai/agent-core.git
cd agent-core
npm install
npm run build      # TypeScript compilation
npm test           # Run all tests (vitest)
npm run typecheck  # Type checking only

License

MIT © 2026 Prismer.AI