A self-hosted, open-source second brain for AI agents and the teams that work with them — built on the ancient method of loci, persistent and queryable. Three paths into one truth layer: fuzzy memory of live agent sessions, a typed mirror of your operational systems, and Locibase — a bitemporal reference graph of curated authoritative knowledge (company policies, contracts & SOWs, sales playbooks, statutes & regulations, anything rule-based that changes over time). One MCP surface. All three paths feed the truth.
The Problem
AI assistants forget. Operational systems silo. Authoritative reference material — internal policies, contracts, sales playbooks, compliance docs, statutes — ages out without anyone noticing. Most platforms pick one and leave the others stranded.
Every session resets. No memory across Claude.ai, ChatGPT, or local agents. The smartest assistant can't build on what it learned yesterday.
Your tax software, CRM, accounting package, and HR system each own a piece of the truth. Cross-cutting reports require fragile ETL stitched together by hand.
Company policies, contracts, sales playbooks, tax statutes, regulations — they all get amended, modified, superseded. Generic search can't tell you what the rule was on a specific past date. Compliance answers, audit responses, and "what did we agree to last quarter?" all need bitemporal awareness, not snapshot scraping.
Third-party memory, BI, and reference services mean your emails, client records, financial data, and even the rulebook you're working against all live on infrastructure you don't control.
Concepts
A handful of terms recur across this page. Each one maps to a real database table and a specific responsibility — knowing them up front makes everything below read straight through.
Palace
Your private, isolated tenant.
Per-organization namespace. Memory, structured data, and reference KBs are all scoped by palace. Each palace gets its own bearer tokens, its own Qdrant collection, and its own K3s namespace. One cluster, many palaces — homelab through enterprise, same architecture.
Locus
A namespace path for recall.
A hierarchical path like business/acme, sessions/claude, policies/security, or sales/playbooks. Every memory is filed under a locus so agents can scope their queries. Think folder structure — but indexed, queryable, and traversable as a graph.
Locigram
The atomic memory unit.
One fact, event, or observation captured as an append-only record. Carries its content, source, locus, confidence, an extracted SPO triple, and the entities it references. The product is named for this unit — locigrams are to Locigram what messages are to a chat app.
Truth
A confidence-scored fact with provenance.
What survives reinforcement and decay. Memory truths come from repeated SPO triples; structured truths come from records you've filed (invoices, contracts, returns, ledger entries, signed SOWs); Locibase truths come from authoritative reference material with valid-time. All three cross-cite and link back to the originating records.
The name Locigram is locus + gram — a written record indexed by spatial namespace. It's a direct nod to the method of loci, the ancient memory-palace technique where you place things-to-remember inside imagined rooms. Locigram is a digital implementation of an idea that's two thousand years old.
How It Works
Operational systems and communications mirror into a typed structured pipeline. Authoritative reference material becomes a bitemporal graph. Live agent sessions plus the hot subset of the other two paths become fuzzy memory — a working layer that reinforces what's actually used. All three reference the same canonical entities and surface through one MCP interface; humans query by REST, SQL, or the Nexus-OS UI.
Memory Path
Structured Path
raw_* schemas — operational systems (CRM, accounting, tax, PSA), communications (email, chat, tickets), and knowledge (wikis, SOPs, captured SME expertise). Typed columns end-to-end — never JSONB blob shrugs.
Locibase Path
Bitemporal = every fact carries both a valid-time (when the policy / clause / rule was actually in force in the real world) and a transaction-time (when we learned about it). That's how Locibase answers "what was the rule on X as of date Y" correctly even after amendments, supersessions, and corrections — whether the "rule" is an internal policy, a contract clause, a sales-comp plan, or a statute.
All three paths produce truths — facts with confidence + provenance. Structured truths come from records you've filed — invoices, contracts, SOWs, returns, ledger entries, time sheets, tickets. Locibase truths come from authoritative reference material with valid-time — your policies, playbooks, statutes. Memory truths come from live sessions plus reinforced promotion of the hot subset of the other two — the working set your agents actually touch. Cross-cited and queryable through one MCP surface.
Data Flow
Sources flow through the connector framework, fan out into three pipelines, converge on shared storage, surface through a single API, and reach any client. Color codes the pipeline each step belongs to.
Diagram scrolls horizontally on narrow screens. Same architecture serves single-tenant homelabs and multi-tenant clusters — each palace gets its own namespace, its own Qdrant collection, and its own scoped bearer tokens.
Truth Engine
Not every memory survives. The Truth Engine continuously reinforces what gets used and decays what doesn't, so the working set stays sharp without ever losing the audit trail. It's the difference between a memory that fades and a fact you can stake a decision on.
Reinforcement
Promotion rule
When 3 or more locigrams assert the same subject–predicate–object triple, the engine promotes them into a single truth. Confidence scales logarithmically with source count — log₂(sourceCount+1) / log₂(20), capped at 0.99 — so the 10th confirmation reinforces more than the 100th. Diminishing returns by design.
Manual correction
An operator can override via the POST /memories/:id/correct REST endpoint. Confidence pins to 1.0; the prior truth is marked superseded but retained for audit. Nothing is ever destructively overwritten.
Cross-path promotion
Hot entities from the structured pipeline and frequently-queried rules from Locibase get materialized as memory truths so agents access them with the same latency as anything else in the working set.
Decay
Forgetting curve
Each truth loses 10% confidence per week without reinforcement (DECAY_RATE_PER_WEEK = 0.10). Modeled on the Ebbinghaus forgetting curve — repeated use is what keeps a fact "fresh".
Graph-centrality boost
A truth that's heavily connected in the graph — cited by many other truths, anchored to active entities — decays up to 33% slower. Well-connected ideas survive longer than orphans.
Archive threshold & cadence
Below 0.15 confidence, a truth is archived (soft-deleted) — invisible to recall but preserved for audit. The engine runs every 6 hours; decay sweep and promotion sweep in the same job.
Two independent dimensions
Every locigram carries a tier (its storage class — hot / warm / cold / noise, controlling whether it lives in Qdrant or Postgres-only) AND a durability class (its decay behavior — permanent / stable / active / session / checkpoint). Two orthogonal dimensions: where it lives versus how fast it fades. A permanent truth in cold tier never decays but isn't pre-indexed for vector search; an active truth in hot tier is fast to recall but only sticks around if it keeps getting used.
Features
First-class Model Context Protocol support. Claude.ai, ChatGPT, Claude Code, and any MCP-compatible assistant can read and write memory + structured data + reference KBs out of the box. 25 MCP tools spanning memory recall, session recovery, structured analytics, graph exploration, connector management, and access control.
Neo4j mirrors every memory as a graph node connected to agents, sessions, loci, and canonical entities. memory_session_start runs GraphRAG traversal — surfaces old memories still connected to your active work, outside the normal time window. Locibase rides the same Neo4j instance for its bitemporal reference graph.
Memories that get used reinforce into durable truths. Memories that don't fade — 10% per week — and eventually archive. Modeled on the Ebbinghaus forgetting curve, with a graph-centrality boost so well-connected ideas survive longer than orphans. See how it works →
Optional GLiNER server pre-tags entities (person, org, location, software, IP, date) before each LLM call. Results are injected as hints — improving extraction quality and reducing hallucinated entities. Fail-open: pipeline continues LLM-only if GLiNER is unreachable.
Plugin connectors auto-activate from environment variables — set the vars, get the source. Categories already shipping include email & messaging, calendar & identity, CRM / PSA, IT & device management, accounting, tax-prep, time & billing, knowledge vaults, agent sessions, and a generic webhook. Most sources mirror 1:1 into the structured pipeline as typed raw_* tables; live agent sessions feed memory; curated reference KBs feed Locibase. The memory layer then promotes the hot subset of structured + Locibase data into fast contextual recall.
Self-hosted on your infrastructure. Your emails, tickets, client records, and reference KBs never leave your network. Postgres is the single source of truth — Qdrant and Neo4j are derived and rebuildable from it.
Structured + memory storage in PostgreSQL. Semantic search via Qdrant. Bitemporal + entity graph via Neo4j. Three storage engines, each with a purpose — all populated by durable background workers that rebuild idempotently from the raw layer.
Daemon watches LLM agent JSONL session files (Claude Code and other coding agents that emit per-session transcripts). Every 5 messages it writes handoff summaries, keeping live-handoff.md and active-context.json current. Multi-agent fleets supported.
Operational systems mirrored byte-for-byte into typed raw_* schemas, then merged into source-agnostic derived.* tables and an entity / evidence / intelligence stack. Per-domain phased rebuilds, idempotent writers, FK-resolved canonical entities, monthly snapshots. No JSONB blob shrugs.
Curated authoritative knowledge in a bitemporal graph — anything rule-based with effective dates. Internal policies, contracts & SOWs, sales comp plans, compliance docs, statutes & regulations. Multi-tier chunking, context scoring, supersession-aware retrieval. Ask "what was the rule on X as of date Y?" and get the version that was actually in force. v1 ships with tax KBs (USC Title 26, IRS bulletins, AFR) as concrete examples.
One-command deployment with Docker Compose. Production-ready Kubernetes manifests for K3s clusters with Longhorn PVCs, initContainer migrations, and namespace isolation per palace tenant.
External LLM Clients
Locigram runs a full OAuth 2.0 + PKCE authorization server. External LLM services authenticate as MCP clients and memories are automatically service-tagged and routed to the correct locus — no model configuration needed.
Claude.ai uses dynamic client registration — it auto-registers itself on first connect. After connecting, tag it in one SQL line and every memory_remember call lands in sessions/claude automatically.
In Claude.ai: Settings → Feature Preview → Model Context Protocol → Add https://mcp.locigram.ai
ChatGPT connectors require a pre-created OAuth client with a client ID and secret. Create one via the admin API and provide it in ChatGPT's connector settings.
Note: ChatGPT's redirect URI changes every time a new connector is created — update oauth_clients redirect_uris after each reconnect.
Supported service loci — each service gets its own isolated namespace:
MCP Tooling
Any MCP-compatible client gets the same surface — recall, context, correction, session recovery, structured-data query, and reference lookup. Configure Locigram as an MCP server in your client of choice; no special framework or agent runtime required.
Core memory surface: memory_remember, memory_recall, memory_session_start, memory_correct, and more. Post-compaction recovery works out of the box — clients call memory_session_start and get back the last several days of decisions and context, GraphRAG-traversed for connected memories outside the normal time window.
An optional daemon watches JSONL session files emitted by coding agents (Claude Code is the reference target) and writes handoff summaries to Locigram. Every five messages it keeps live-handoff.md and active-context.json current. Supports dynamic agent discovery, concurrent multi-session tracking, fleet status via GET /api/context/fleet, and 10-minute heartbeats.
Wire it up in three steps
Deploy Locigram → add the MCP server entry to your client config → start chatting.
Connectors
Connectors auto-activate from environment variables — set the vars, get the source. The framework is the product; specific source adapters are pluggable. Almost everything mirrors into the typed structured pipeline; live agent sessions feed memory directly; curated reference KBs feed Locibase. Memory then promotes the frequently-queried slice of structured + Locibase data into fast contextual recall. New categories ship as separate @locigram/connector-* packages.
Email & Messaging
Conversational sources
SMTP/IMAP, hosted mail providers, team chat, SMS — typed mirror into the structured pipeline (sender / recipient / thread / body / timestamp). Frequently-touched threads get promoted into memory. Examples shipping: Microsoft 365 email + Teams, Gmail, generic IMAP.
Calendar & Identity
Who and when
Calendar feeds and directory sources mirror into structured tables and feed the entity-resolution layer. Examples shipping: Microsoft 365 calendar + people directory.
CRM & PSA
Customer + ticketing systems
Typed mirror into raw_* — tickets, contacts, assets, SLAs. Example shipping: HaloPSA.
IT & Device Management
Endpoint & infra inventory
Devices, agents, alerts, patches. Pre-classified fast path skips the LLM. Example shipping: NinjaOne.
Accounting & AR
Ledgers, invoices, payments
Source-of-truth typed mirror into the structured pipeline. Examples shipping: QuickBooks Online + Desktop (via bridge).
Tax Prep
Returns, projections, e-file
Per-year normalized returns + filing status. Examples shipping: Lacerte (via on-premise bridge).
Time, Billing & PM
Engagements, projects, sheets
Staff time, engagement scope, billing decisions, project status. Examples shipping: OfficeTools, PracticeCS (via bridge).
Knowledge & Notes
Personal & team vaults
Curated documents, SOPs, runbooks, captured SME Q&A — typed mirror with summarization + deep-link backreferences. Examples shipping: Obsidian (with LLM-graded indexing worthiness).
Agent Session Capture
LLM agent transcripts (memory path)
The one source that feeds directly into the memory pipeline rather than via structured. Daemons watch JSONL session files emitted by coding agents (Claude Code reference target), generate handoff summaries, keep live-handoff.md always current. Fleet status endpoint included.
Reference KBs (Locibase)
Authoritative external knowledge
Bitemporal ingestion of any rule-based corpus — internal policies, contracts, sales comp plans, compliance docs, statutes. Examples shipping (tax domain first): US Tax Code, IRS Internal Revenue Bulletin, Applicable Federal Rates.
Generic Webhook
Always-on escape hatch
Push anything to /api/ingest from any system that can POST. No env vars required.
Quick Start
Clone, configure, and start. Locigram runs anywhere Docker runs.
# Clone the repo git clone https://github.com/locigram/locigram.git cd locigram # Configure cp .env.example .env # Set PALACE_ID, API_TOKEN, POSTGRES_PASSWORD # Optional: NEO4J_URL, GLINER_URL, connector env vars # Start docker compose -f deploy/docker/docker-compose.yml up # API: http://localhost:3000 # MCP: http://localhost:3000/mcp
Architecture
Multi-repo TypeScript monorepos. Each package owns its dependencies. Swap, extend, or contribute to any layer independently. Multi-tenant by namespace (palaces) — one cluster hosts many independent organizations with hard data isolation.
| Package / Component | Description |
|---|---|
| Memory path — locigram repo | |
| @locigram/server | Hono REST API + MCP server (Streamable HTTP). OAuth 2.0 + PKCE authorization server for external LLM clients. Background workers: embed, graph, truth, derived-refresh. Docker entry point. |
| @locigram/pipeline | Memory extraction loop — GLiNER NER pre-extraction, LLM SPO-triple extraction, dedup by source_ref, entity resolution against the canonical evidence layer, embed + store. Inputs are live agent sessions and cross-path promotion candidates (hot structured entities and Locibase rules), not raw external sources. |
| @locigram/truth | Truth engine — Ebbinghaus decay scoring, tier promotion (hot/warm/cold), co-occurrence clustering, noise re-assessment. Nightly sweep CronJob. |
| @locigram/vector | Qdrant wrapper. One collection per palace. Semantic search layer. Populated by embed-worker every 30s. |
| @locigram/db | Drizzle schema + raw SQL migrations. Runs as K8s initContainer on every deploy. Owns the public, raw_*, derived, evidence, and intelligence schemas. |
| @locigram/connector-* | Plugin source adapters — auto-registered from env vars. New categories ship as new packages. See Connectors section above for current categories. |
| session-monitor | Optional agent-session daemon. Watches JSONL files emitted by coding agents (Claude Code is the reference target), generates handoff summaries, supports multi-agent fleets with dynamic discovery and concurrent session tracking. |
| Structured pipeline — locigram repo (derived domains) | |
| raw_* | Per-source typed mirror schemas — raw_quickbooks, raw_officetools, raw_practicecs, raw_lacerte, raw_halopsa, etc. Connectors copy source tables 1:1. No JSONB. Indexed by palace + firm. |
| derived.* | Per-domain unified views — Tax, People, Financial (AR + AR-adjacent), Time Tracking, … . Idempotent writers; rebuildable from raw. Phased per-domain rearchitecture program (Phase R) hardens one domain at a time. |
| evidence.* | Cross-source entity resolution — deterministic UUIDs anchored on a primary source (e.g. Lacerte for tax-paying entities). Five-pass merge with FK arrays back to every source-system ref id. |
| intelligence.* | Monthly snapshots pre-computed for each entity — health, profitability, utilization, signals. Drives at-a-glance dashboards without re-running expensive cross-domain aggregations on query. |
| Reference graph — locibase repo | |
| @locibase/server | Independent Hono REST API for curated reference KBs. Scoped bearer tokens (kb:read / kb:write / kb:sync / kb:admin). Versioned API surface (/api/v1/...). |
| @locibase/kb-* (forthcoming) | One package per knowledge base — pluggable. The first KB is tax (USC Title 26, IRS IRB, IRS AFR) because that's our anchor use-case, but the same pattern extends to internal-policy KBs, contract libraries, sales-comp plans, compliance docs — anything rule-based with effective-dated content. Each KB owns its source fetchers, parsers, and supersession rules. |
| Bitemporal graph (Neo4j) | Rule / Version / Amendment / Cross-reference nodes with effective-date ranges on every edge. Powers "what was the rule on X as of date Y" with the version actually in force. |
| User-facing surfaces & tooling — sibling repos | |
| nexus-os | Operator-facing web UI. Browse entities, drill into structured data, audit derived rollups, manage palaces and firms. Talks to the same Hono API the LLMs use. |
| locigram-admin | Tenant admin UI — palace + firm provisioning, connector configuration, token issuance, fleet observability. |
| locibook | Client-facing book / portal surface backed by the same structured pipeline. Read-only views of an entity's own records. |
| locigram-web | This marketing site (you are here). Static, public, no data plane. |
| loci-extract | On-premise bridge daemons for source systems that don't expose cloud APIs — Lacerte SDK, QuickBooks Desktop, OfficeTools, PracticeCS. Push to the server over a local HTTPS endpoint. |
| Optional / supporting components | |
| Neo4j | Shared graph engine — memory graph (Memory nodes connected to Agent / Session / Palace / Locus / Entity) and Locibase bitemporal graph live side by side. Powers GraphRAG in memory_session_start and supersession queries in Locibase. |
| GLiNERoptional | NER pre-extraction server. Detects entities before each LLM call. Fail-open — pipeline continues LLM-only if unavailable. |
| obsidian-auditoptional | Weekly LaunchAgent. LLM-evaluates each Obsidian vault note for indexing worthiness. Writes approved index to ~/.locigram/obsidian-index.json. |
| obsidian-syncoptional | Nightly LaunchAgent. Summarizes approved Obsidian notes via LLM, upserts to Locigram with deep links. |