agentic-cortex v7.4.0 — The 5-Layer Agent Brain + Test-Time Reasoning

Persistent, self-improving memory and orchestration for AI coding agents and developer tools. Implements the full 5-Layer Graph Engineering framework: Prompt Engineering → Context Engineering → Harness Engineering → Loop Engineering → Graph Engineering. Install & forget — auto-injects context via git hooks, infers what you're working on, detects when improvement stalls, coordinates multi-agent teams, and prevents the same mistakes from repeating across projects.

Features

• Zero-arg bootstrap — agentic-cortex bootstrap with no arguments. Infers your task from session prompt, git branch, or recent activity. Returns structured XML context.
• Auto type detection — save "title" "content" detects the right memory type from content patterns. No --type flag needed.
• Machine-wide global vault — battle-tested learnings auto-promoted across projects. If you learned it once, you never make the mistake again on this machine.
• Auto-promotion with relative thresholds — top 20% confidence + 2× median utility auto-promote to global vault during reflection. Self-tunes as your project grows.
• XML codebase graph — deterministic static analysis, SHA-256 cached, zero LLM cost. Injected as structured XML, not markdown.
• Symbol-level code index — every function/method/class with its real body indexed in SQLite. Bootstrap injects task-scoped symbols (relevant files + transitive import closure) with actual code, not just a static map — so agents know the code, not just its shape.
• Semantic code search — symbols are embedded (BGE) and hybrid-searched by meaning (code-index search "token budget calc" --semantic finds the budget-forcing code).
• Change-aware ingestion — git hooks re-parse only the changed files (partial graph regen) and record a "code change" memory after every commit/merge/pull. The index keeps up as the codebase grows.
• Distilled symbol summaries — one-line LLM summaries (docstring fallback) cached per symbol, so more symbols fit the same token budget.
• Usage-weighted injection — every symbol an agent retrieves is tracked (access_count/last_accessed_at) and fed back into task-scoped selection: frequently-needed code wins ties and becomes the fallback when a task matches nothing.
• Memory-safe by default — the ~400MB embedding model is NEVER auto-loaded. Search/bootstrap/sync stay keyword-only unless you opt in with AGENTIC_CORTEX_EMBEDDINGS=1 or an explicit embedding command (code-index embed, search --semantic). No more OOM halts on weak machines.
• Session context compactor — map-reduce compression of observations or transcripts into a "state so far" summary (~95% smaller) that replaces raw conversation history — attacks the biggest token cost: per-turn history re-sending.
• Evidence-theoretic conflict resolution (Dempster-Shafer) — contradictory observations are no longer superseded silently. Each side gets a belief mass (confidence + corroboration + usage); the statistical channel is fused with LLM adjudication via Dempster's rule. Adjudication is a two-shot debate: first the LLM builds the strongest case for each side (adversarial argument generation, preventing judge anchoring), then judges with both cases on the record — the full deliberation is persisted for auditability. The resolution records the conflict coefficient k, the combined belief, and the deciding evidence; the winner's boost is agreement-weighted (a knife-edge k≈1 resolution gets almost none). Bootstrap injects recent resolutions as <settled_debates> so agents see why a debate was settled instead of re-opening it — and flags weak resolutions (high conflict coefficient k, statistical near-tie, or a winner that never clearly out-massed the loser) with a severity="weak_resolution" warning so agents treat the topic as an OPEN QUESTION, not settled precedent. Human/agent-guided resolution via agentic-cortex resolve --winner ID --loser ID --reason ....
• Agent-optimized knowledge.md — XML-structured, 4× token reduction vs markdown. Built for LLM consumption, not human skimming.
• 138 MCP tools — memory_bootstrap(), memory_search_all(), memory_machine_vault(), memory_promote_global(), plus a multi-agent mailbox (memory_send/memory_inbox), provider discovery (memory_provider), recovery (probe-gated retry), prompts, plateau detection, workflows, FSM, rules, test-time reasoning (tree search/PRM/self-consistency/budget forcing), failure classification, experience replay, translation store, burst budget, war room, deterministic reasoner (6 modes), and persona swarm orchestration. Stdio JSON-RPC.
• Agent capability manifest (schema v1) — machine-readable JSON (manifest / discover CLI, memory_manifest / memory_discover / memory_compose MCP tools) declaring 40+ capabilities with versions and interfaces for feature-detection, auto-discovering compatible agent frameworks and generic MCP clients via their config files / env vars / registered MCP servers, and returning the exact wiring to compose with each — which MCP config to write and which memory/reasoning/audit/orchestration tools to expose.
• 13 typed memories — instruction, fact, decision, goal, commitment, preference, relationship, context, event, learning, observation, artifact, error.
• Hybrid search — FTS5 keyword + BGE semantic embeddings (768-dim) + cross-encoder reranking. Falls back gracefully when embeddings unavailable.
• Confidence & provenance tracking — every memory scores 0-100 confidence and source (explicit, inferred, observed).
• 5-Layer Graph Engineering — full implementation of Prompt Engineering (versioned template registry), Context Engineering (hybrid search + reranking), Harness Engineering (MCP tools + webhooks), Loop Engineering (self-improvement + plateau detection), and Graph Engineering (FSM + rules + multi-agent DAG workflows).
• Prompt template registry — 20 versioned, outcome-tracked templates for every LLM call. Render templates with variable substitution via API or MCP. Centralized prompt evolution powered by eval log feedback.
• Self-improving loop with meta-cognition — error RCA generates systemic learnings. Conflict detection finds contradictions. Evidence-based confidence scoring. Plateau detection identifies stalled improvement and triggers breakthrough analysis.
• Multi-agent workflows — DAG-based workflow executor with FSM bridge. Workflow steps can spawn sub-agents tracked in state machines. Built-in multi-agent workflows: code-review-team, incident-response-squad.
• FSM orchestration engine — state machines for coding, debugging, and review workflows. Agents transition between states with guard conditions and entry/exit actions.
• Declarative rule engine — priority-based condition→action rules that fire on events. Built-in rules for error escalation, auto-crystallization, and context capture.
• Webhook support — hook actions can POST to external HTTP endpoints with template interpolation and configurable retries. Bridge agentic-cortex to Slack, PagerDuty, CI pipelines, or any HTTP service.
• Save-time deduplication — cosine similarity ≥ 0.97 reinforces existing memories instead of creating duplicates.
• Temporal forgetting (supermemory-inspired) — temporary facts get bounded lifespans: save --expires ISO / --ttl-days N, or automatic detection of dates and relative spans in content ("exam tomorrow" dies on its date, not via slow decay). An expiry sweep runs in every maintenance cycle; expired memories drop out of all retrieval.
• Supersession — "Deploy is Monday" now supersedes "Deploy is Friday": newer statement-like facts (fact/decision/preference/context/learning) with near-identical titles mark the old one superseded_by and record a supersedes relation for lineage. Old fact stays in the vault for audit but never surfaces again. Fuzzy contradictions still go through the Dempster-Shafer debate pipeline.
• One-call profile (profile) — supermemory-style project/agent profile: static (stable facts/decisions/preferences ranked by confidence × corroboration × layer) + dynamic (open goals, commitments, last-7-days activity) + optional combined search, all in a single fast deterministic call. MCP: memory_profile. Also auto-injected at session start: bootstrap emits a <project_profile> block (with <stable_knowledge> and <current_activity> sections) so agents get the profile without an extra round trip — opt out with includeProfile: false.
• Unified search (hybrid) — memories AND code symbols in one query (AC's answer to supermemory's hybrid RAG+memory): returns { memories, code } with source tags. MCP: memory_search_hybrid.
• Provider adapter + recall@k suite — MemoryBench-compatible surface (addMemories/searchMemories/getProfile/reset) so external harnesses can benchmark AC head-to-head against supermemory, Mem0, and Zep, plus a built-in deterministic recall@k suite (benchmark recall) covering single-hop, multi-hop, temporal, and knowledge-update categories. Memory quality claims are now measurable, not just asserted. Verified end-to-end against supermemoryai/memorybench (the real harness: registered provider, ingest→index→search through its orchestrator) — see the granularity-controlled comparison: at matched session-level units, AC beats MemoryBench's filesystem baseline on LoCoMo recall@10 (63.0% vs 54.2%), with multi-hop at 80% vs 30.8%. The supermemory cloud row is one keyed run away (scripts/supermemory-smoke.js validates, then the v3 runner adds it with sampling + caching).
• Profile project-scoping fix (v7.4.0) — profile() and the auto-injected <project_profile> block now filter strictly by project_path; previously they could surface memories from any project on the machine, crowding out the project's own facts from the top-N. Regression-tested.
• Temporal forgetting + supersession test suite (v7.4.0) — src/core/forgetting.js (TTL/expiry detection) and src/bench/provider-adapter.js gain dedicated suites (tests/forgetting.test.js, 32 tests) with per-run isolated databases.
• Freshness scoring — 0-100 score combining access recency, confidence, and utility. Auto-archives stale memories.
• Auto-maintenance scheduler — runs freshness updates and archival every ~50 saves, minimum 6 hours between full cycles.
• Tiered memory crystallization — raw observations compress upward through layers: raw (1) → synthesis (2) → principle (3). Principles are always-injected, load-bearing knowledge.
• Immutable evaluation log — append-only audit trail (AutoGTM's results.tsv pattern). Every evaluation preserved forever for benchmarking and plateau detection.
• Intent → Action → Outcome tracking — linked triplets with relations for evidence-based learning verification.
• Multi-agent sharing — namespaced agent sessions with shared memory discovery.
• Skill/procedure extraction — structured fields (steps, triggers, preconditions, postconditions) with dedicated search.
• Pre-loaded coding standards — DRY, KISS, SOLID, Clean Code, Karpathy guidelines auto-seeded on init. Always injected into context.
• Conversation transcript ingestion — regex + LLM fallback extracts decisions, errors, learnings, preferences, and facts from chat logs.
• Grounded QA — retrieve relevant memories + LLM answer with source citations.
• Git hook auto-injection — context auto-refreshes on checkout, merge, pull, and commit.
• Multi-agent discovery files — auto-creates .claude/CLAUDE.md, .cursor/rules/agentic-cortex.mdc, .opencode/agentic-cortex.md.
• Temporal queries — search as-of specific dates or filter by changes since.
• Daily summaries — LLM-generated or template-fallback summaries of each day's observations.
• Obsidian export — one-way read-only mirror to an Obsidian vault with wikilinks and tag indexes.
• File upload — chunk and embed .md, .txt, .json, .csv, .py, .ts, .prisma, and more into memory.
• HTTP API server — optional REST interface on port 37777 for external tool integration.
• Multi-agent discovery — auto-creates discovery files for Claude Code, Cursor, and OpenCode on setup.
• 🌳 Tree of Thoughts / MCTS reasoning — inference-time graph search over reasoning branches. Beam search, MCTS, and greedy strategies with adaptive compute budget.
• 🔍 Process Reward Model (PRM) — 3-tier step-level verification: deterministic checks, LLM-as-judge, and memory cross-check. Scores each reasoning step 0.0-1.0.
• 📊 Adaptive compute budget — Snell et al. compute-optimal allocation: estimates problem difficulty from memory and adjusts beam width, depth, and token budget.
• 💻 Program-aided reasoning (PAL/PoT) — generate and execute verification code in a sandbox. Deterministic arithmetic, graph traversal, and constraint checking.
• 🔄 Reflexion loop — in-context self-correction: failed reasoning paths become memory, preventing repeated mistakes within the same session.
• 🗳️ Self-consistency decoding — sample N independent chains with temperature, majority-vote the answer. Optional PRM-weighted voting gives higher-quality paths more influence.
• 💪 Budget forcing (s1) — enforce minimum reasoning depth by suppressing early stops and appending doubt heuristics. Force conclusion synthesis at upper token bound. Controls compute per problem independently of architectural changes.
• BGE embeddings — Xenova/bge-base-en-v1.5 with in-memory LRU cache.
• Embedding dimension mismatch detection — warns when stored embeddings don't match current model dimensions.
• Calibrated, settleable commitments (YOINK-inspired) — confidence is graded, not just stored: feedback records an immutable event with the confidence held at judgment time, and analytics/memory_calibration report per-type overconfidence gap and Brier score. Structured claims (claim + test + settle_date + optional read_source) settle themselves — maintenance sweeps due ones, reads the source, and writes the outcome back into the calibration loop. Unverifiable predictions are refused at save time with a stated reason, a dead-memory audit surfaces never-retrieved/never-linked memories as a health metric, and rebuild --from-export treats the SQLite vault as a rebuildable index over the markdown/JSON export.
• Tamper-evident eval log — append-only entries are hash-chained (hash_n = sha256(entry_n | hash_{n-1})); doctor verifies the chain end-to-end and names the exact line where an edit occurred. Tamper-evident, not tamper-proof — and regression-tested with a demonstrated full rewrite.
• Honest docs (scripts/check-readme.js) — recomputes MCP tool count, memory types, prompt templates, and test files straight from source and fails if the README's numbers disagree (YOINK's figures.py --check pattern).
• Capability-absence testing — the read-only/no-embed guarantees are enforced by tests that parse the source and prove the capability is absent, not just by runtime checks.

Install

npm install -g agentic-cortex

Lightweight install (no semantic embeddings)

Semantic search and reranking are powered by @xenova/transformers, which is an optional dependency — the core package (SQLite storage, FTS5 keyword search, consolidation, self-improvement, MCP tools) works fully without it and degrades semantic features to deterministic keyword search.

# Skip the ~500 MB embedding stack entirely (~12 MB install)
npm install -g agentic-cortex --omit=optional

# Add semantic embeddings back later
npm install -g @xenova/transformers

Quick Start

New here? Start with QUICKSTART.md — wire into your agent in two minutes. Deep dive: ARCHITECTURE.md. Contributing: CONTRIBUTING.md. Runnable demos: node examples/offline-demo.js (fully offline memory loop) and node examples/mcp-demo.js (speaks real MCP JSON-RPC like your agent does).

cd your-project

# One command: init + graph + inject + discovery files + git hooks
agentic-cortex setup

# At session start, just run:
agentic-cortex bootstrap

Core Commands

| Command | Description | |---|---| | bootstrap | 🔑 Bootstrap task context — zero args, auto-inferring | | save <title> <content> | Save observation — type auto-detected | | search <query> | Hybrid search (FTS5 + semantic) with optional --rerank | | machine-search <query> | Search across ALL projects on this machine | | machine-memory | View/search the machine-wide global vault | | promote-global <id> | Promote a memory to machine-wide scope | | feedback <id> --type helpful\|incorrect | Reinforce or flag a memory | | forget <id> | Soft-delete (--hard for permanent) | | get <id> | View full memory with structured fields | | edit <id> | Edit memory (version history preserved) |

How It Works

Zero-Arg Bootstrap

bootstrap infers your task and returns structured XML context:

<agentic_cortex_context project="/my/project" task="fix login bug">
  <session_started id="sess_abc123"/>
  <actionable_insights>...</actionable_insights>
  <relevant_memories>
    <tier priority="critical">...</tier>
    <tier priority="important">...</tier>
  </relevant_memories>
  <recent_sessions>...</recent_sessions>
  <warnings>...</warnings>
  <coding_standards collapsed="true">...</coding_standards>
  <global_vault>...</global_vault>
  <codebase_graph>...</codebase_graph>
</agentic_cortex_context>

Machine-Wide Global Vault

Auto-promote uses relative thresholds — the system gets stricter as your project grows:

# View cross-project analytics
agentic-cortex machine-memory --analytics

# Search across all projects
agentic-cortex machine-search "Windows path normalization"

# Manually promote
agentic-cortex promote-global 42

Temporal Forgetting, Profile & Unified Search (supermemory-inspired)

# Temporary facts with bounded lifespans
agentic-cortex save "Exam" "User has an exam tomorrow"   # expiry auto-detected
agentic-cortex save "Trial" "API trial key active" --ttl-days 7

# Sweep expired memories (also runs automatically in maintenance)
agentic-cortex expire [--dry-run]

# One-call profile: static facts + dynamic activity (optional combined query)
agentic-cortex profile [--q "deploy schedule"] [--agent ID]

# Unified search: memories + code symbols in one query
agentic-cortex hybrid "token budget calculation" [--no-code] [--rerank]

# Benchmark recall@k (deterministic, no dataset needed)
agentic-cortex benchmark recall

Code Index & Context Compaction (v7)

# Build the symbol-level index (functions/methods/classes + real bodies)
agentic-cortex code-index ingest [--embed] [--summarize]

# Re-parse only git-changed files (runs automatically via post-commit/merge hooks)
agentic-cortex code-index ingest --changed-only

# Find code by name OR meaning
agentic-cortex code-index search "hybrid search"
agentic-cortex code-index search "token budget calculation" --semantic --body

# Distilled one-line summaries + semantic vectors
agentic-cortex code-index summarize
agentic-cortex code-index embed

# Compact session context into a "state so far" summary
agentic-cortex compact [--session ID] [--save-observation]

Bootstrap automatically includes a <code_symbols> block with real bodies for the files relevant to the current task. MCP tools: memory_code_symbols, memory_code_context, memory_ingest_code, memory_code_stats, memory_compact_context.

Usage feedback loop — every retrieval bumps a symbol's access_count, and task-scoped injection prefers frequently-needed code (code-index top shows the hot list). This is a local behavioral signal and is not synced between machines.

Memory safety (important) — the BGE embedding model loads ~400MB into the process, so embeddings are disabled by default to prevent OOM halts on memory-constrained machines. All automatic paths (bootstrap, search, git-sync re-embed) degrade to fast keyword search. To enable semantic features:

export AGENTIC_CORTEX_EMBEDDINGS=1   # global opt-in
# or per-command (explicit):
agentic-cortex code-index embed
agentic-cortex code-index search "token budget calc" --semantic

Auto-Detect Memory Types

| Pattern | Type | Example | |---|---|---| | "error", "bug", "crash", "failed" | error | save "Null ptr" "Error in auth.ts:42" | | "chose", "decided", "going with" | decision | save "DB" "Chose SQLite over Postgres" | | "learned", "realized", "found that" | learning | save "Paths" "Windows needs forward-slash" | | "prefer", "rather than" | preference | save "Style" "Prefer async/await" | | "project uses", "configured with" | fact | save "Stack" "Uses Prisma with PostgreSQL" | | "step", "procedure", "how to" | instruction | save "Deploy" "Step 1: build, step 2: push" | | "published", "released", "deployed" | event | save "Release" "Published v4.7.0 to npm" | | "goal", "objective", "milestone" | goal | save "Target" "Need to achieve 95% coverage" |

All Commands

Core

bootstrap save search get edit forget list bulk

Intelligence

conflicts resolve answer analytics daily-summary reflect maintenance freshness crystallize eval-log

Brain Orchestration

fsm rules workflow experiment

Cross-Project

machine-memory machine-search promote-global transfer feedback

Setup

setup init graph inject hook embed

Advanced

upload watch action trail utility ingest export serve standards context session timeline cortex-ui

MCP Server

agentic-cortex-mcp

138 tools over stdio JSON-RPC. Call memory_bootstrap() with no arguments to start.

Graph Engineering Tools

| Tool | Layer | Description | |------|-------|-------------| | memory_prompts_list | Layer 1: Prompt Engineering | List all 20 versioned prompt templates | | memory_prompts_render | Layer 1: Prompt Engineering | Render a template with variable substitution | | memory_plateau_check | Layer 4: Loop Engineering | Detect stalled improvement; triggers breakthrough analysis | | memory_workflow_agents | Layer 5: Graph Engineering | List FSM-tracked sub-agents in multi-agent workflows | | memory_fsm | Layer 5: Graph Engineering | Manage agent state machines (start, transition, query) | | memory_rules | Layer 5: Graph Engineering | Manage declarative brain rules (list, enable, disable, evaluate) | | memory_workflow | Layer 5: Graph Engineering | Run multi-step DAG workflows with dependency ordering | | memory_crystallize | Layer 4: Loop Engineering | Compress raw observations upward through tiered layers | | memory_experiment | Layer 4: Loop Engineering | Spawn/list controlled experiments (hypothesis testing) | | memory_eval_log | Layer 4: Loop Engineering | Query the immutable evaluation log for benchmarking |

For Coding Agents (Use AC as Your Memory Provider)

agentic-cortex is not a hosted/cloud service — there is no central server to "deploy" AC to. It runs locally on the same machine as your coding agent, in one of two forms:

1. MCP server (stdio subprocess). agentic-cortex-mcp is a zero-arg binary. The coding agent launches it as a child process and speaks JSON-RPC over stdin/stdout. Register it once in the agent's own config, then call memory_bootstrap({}) at session start and memory_save({...}) after decisions and fixes.

   | Coding agent | Where to register the server | |---|---| | Claude Code | .mcp.json (project) or claude_desktop_config.json (global) | | Cursor | .cursor/mcp.json | | OpenCode | opencode.json → mcpServers | | Freebuff | .freebuff/mcp.json | | Gemini CLI | .gemini/settings.json → mcpServers | | OpenAI Codex CLI | ~/.codex/config.toml → [mcp_servers.*] (TOML stanza printed by wireup) | | GitHub Copilot CLI | .copilot/mcp-config.json | | VS Code (Copilot agent mode) | .vscode/mcp.json → servers | | Windsurf | .windsurf/mcp_config.json | | Roo Code | .roo/mcp.json | | Zed | .zed/settings.json → context_servers | | Cline / Kilo Code | VS Code extension settings (manual paste — wireup prints the JSON) | | Continue / Goose | YAML config (block printed by wireup, never auto-merged) | | Amazon Q | .amazonq/mcp.json | | Amp / Crush / Trae / Qwen Code | .amp/settings.json / .crush/crush.json / .trae/mcp.json / .qwen/settings.json | | Aider | No native MCP — instructions via CONVENTIONS.md (--read) | | Any MCP client | { "mcpServers": { "agentic-cortex": { "type": "stdio", "command": "agentic-cortex-mcp", "args": [] } } } |

   One command wires them all: agentic-cortex wireup detects which agents are present (config files, home-dir configs, env vars, PATH executables), merges the AC MCP registration into every JSON config it finds (preserving sibling servers), and injects a version-stamped instruction section telling each agent that AC owns memory, sessions, and machine-wide knowledge. YAML and TOML configs are never auto-merged — wireup prints the exact stanza instead. Idempotent; preview with --dry-run.

2. Node library (in-process). For agents that embed AC directly (e.g. a custom orchestrator or the cortex-swarm persona swarm): require('agentic-cortex'), or set AGENTIC_CORTEX_PATH to its src/api/index.js.

Where the memory lives: a single machine-global SQLite file — %APPDATA%/agentic-cortex/agentic-cortex.db on Windows and ~/.local/share/agentic-cortex/agentic-cortex.db on Linux/macOS (override with AGENTIC_CORTEX_DB). There is no database server to point at; each machine runs its own brain. Cross-machine sharing uses the optional git memory repo (agentic-cortex setup + AGENTIC_CORTEX_MEMORY_REPO), not a live server.

Distributed learning: seeds, not dumps

Knowledge gathers locally on each machine and travels only as small, self-contained seeds — and every seed has a bounded lifespan:

1. Gather — every wired agent writes into the one local vault. Nothing leaves.
2. Distill — reflection + crystallization compress raw observations into battle-tested learnings.
3. Screen — the seed sanitizer hard-blocks credential-class content (private keys, JWTs, tokens, passwords) and redacts secrets, connection strings, emails, user paths, and IPs before anything can leave. Over-redacted or machine-specific content is kept local. Fail-closed: if the gate errors, nothing is exported.
4. Seed — passing seeds are wrapped in a lifecycle envelope (pseudonymous machine id — no hostname/username/serial — plus a per-type TTL) and pushed as markdown to the git memory repo. Identity, session IDs, and project paths never travel.
5. Germinate — other machines import seeds into a quarantined advisory state: confidence capped at 60 (proven on another machine, not this one), decaying with age, tagged seed.
6. Graduate or expire — when a local agent re-proves a seed (same failure, feedback helpful, corroborated save), its confidence climbs and at 85 it graduates to a full local memory. Un-corroborated seeds age out and are dropped at import once expired. Local evidence always outranks seed trust.

Discover yourself: call the memory_provider MCP tool for the provider manifest (name, version, memory/relation types, multi-agent mailbox, workflows, recovery, and usage instructions).

26 Memory Types

instruction fact decision goal commitment preference relationship context event learning observation artifact error success failure pattern synthesis principle experiment procedure skill action architecture bugfix gotcha codebase-graph

18 core types plus success/failure, the skill/procedural types, and legacy aliases (accepted for backwards compatibility).

Tiered Memory Layers (AutoGTM's Compounding Brain)

| Layer | Type | Description | |-------|------|-------------| | 1 — Raw | observation, error, fact, decision, etc. | Direct observations from agent activity | | 2 — Synthesis | learning, synthesis, pattern | LLM-compressed clusters of related raw observations | | 3 — Principle | principle | Battle-tested knowledge verified 3+ times; always injected in context |

Environment

| Variable | Default | Description | |---|---|---| | AGENTIC_CORTEX_PROJECT | cwd | Default project path | | AGENTIC_CORTEX_SESSION | — | Current session ID | | AGENTIC_CORTEX_PORT | 37777 | HTTP server port | | LLAMA_CPP_BASE_URL | http://127.0.0.1:8081 | LLM for summaries/QA | | AGENTIC_CORTEX_LLM_PROVIDER | openai | openai | xenova | off — model provider (see src/core/llm-adapter.js) | | AGENTIC_CORTEX_LLM_BASE_URL | LLAMA_CPP_BASE_URL | Any OpenAI-compatible endpoint (llama.cpp, LM Studio, Ollama, vLLM, OpenRouter, OpenAI) | | AGENTIC_CORTEX_LLM_MODEL | server default | Model name | | AGENTIC_CORTEX_LLM_API_KEY | — | Bearer token for hosted providers | | AGENTIC_CORTEX_LLM_LOCAL_MODEL | Xenova/LaMini-Flan-T5-77M | Local model for the xenova provider | | AGENTIC_CORTEX_LOG | pretty | pretty | json structured logs | | AGENTIC_CORTEX_LOG_LEVEL | info | debug | info | warn | error |

Reproducible environments & observability

docker compose up --build      # Dockerfile + compose, vault persisted in a named volume
docker compose run --rm demo   # offline demo against the shared vault

VS Code users: open the repo and "Reopen in Container" (.devcontainer/).

When serving (agentic-cortex serve):

• GET /health — vault stats + LLM provider status + uptime (JSON)
• GET /metrics — Prometheus gauges (?format=json also supported)
• AGENTIC_CORTEX_LOG=json — one JSON object per log line, shipper-ready

Architecture: The 5-Layer Graph Engineering Brain

Layer 1: Prompt Engineering  ──  src/core/prompts.js     (20 versioned templates)
Layer 2: Context Engineering  ──  src/core/search.js       (hybrid FTS5 + semantic)
                                  src/core/embedding.js    (BGE-base, cross-encoder)
                                  src/core/relations.js    (memory graph)
Layer 3: Harness Engineering  ──  src/mcp/server.js       (93 MCP tools, webhooks)
                                  src/core/hooks.js        (event-driven automation)
Layer 4: Loop Engineering     ──  src/core/self-improve.js (6 improvement hooks)
                                  src/core/reflection.js   (consolidate, crystallize)
Layer 5: Graph Engineering    ──  src/core/fsm.js          (state machine engine)
                                  src/core/rules.js        (declarative rule engine)
                                  src/core/workflow.js     (DAG workflow + multi-agent)

License

MIT © 2026 zallauddin

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files, to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.