AutoGineer
Generated banner for LongMemory
Generated logo for LongMemory

LongMemory

Memory server

Created by CaviraOSS

Published in CaviraOSS/LongMemory. Publisher page

4,573 GitHub stars

What it is

LongMemory Hydrograph TypeScript package: library, CLI, self-hosted API server, and benchmark harness.
— the description by CaviraOSS

AutoGineer overview, from the brain’s own files

LongMemory is a cognitive memory engine designed to provide AI agents with durable, governed, and temporal recall. Unlike standard RAG pipelines that rely on simple vector similarity, LongMemory utilizes a Hydrograph substrate to manage immutable nodes, executable edges, and temporal truth. It supports complex recall modes including strict, historical, associative, and world-grounded retrieval. The system is built for local-first deployment using SQLite, offering a self-hosted API server, CLI, and native integrations for various agent frameworks, IDEs, and automation tools. It enforces governance policies across projects, users, and teams, ensuring that memory remains grounded, explainable, and context-aware.

How it works

Memory model: LLM wiki

AutoGineer overview, from the brain’s own files

LongMemory operates as a memory server that stores data in a local SQLite database. It ingests events, documents, and session data into a Hydrograph structure. When an agent needs information, the system performs recall based on specific modes—such as strict, historical, or associative—to retrieve relevant, token-bounded context. The engine supports governance by scoping memory to specific projects, tenants, or users. It provides an API for agents to interact with this memory, and includes tools for maintenance, such as decay and reinforcement, to manage the lifecycle of stored information.

Folders
FolderRoleFiles
.githubagent-config13
docsdocs34
packagessource-code7
srcsource-code340
toolsscripts5
.agentsfolder1
.dofolder1
appsfolder19
benchmarksfolder32
dashboardfolder34
integrationsfolder47

Requirements

Apps: Docker

Runtimes: Node.js >=20

Databases: SQLite

API keys (by name): AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AZURE_DEVOPS_TOKEN, BITBUCKET_TOKEN, GEMINI_API_KEY, GITHUB_TOKEN, GITLAB_TOKEN, GOOGLE_ACCESS_TOKEN, LINEAR_API_KEY, LONGMEMORY_API_KEY, MICROSOFT_GRAPH_TOKEN, NOTION_API_KEY, NVIDIA_API_KEY, OM_API_KEY, OM_GEMINI_API_KEY, OM_OPENAI_API_KEY, OM_SIRAY_API_TOKEN, OPENAI_API_KEY, SIRAY_API_TOKEN, SLACK_BOT_TOKEN

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Google Antigravity, Kiro, OpenCode, Amp, Roo Code, Cline, JetBrains Junie, Devin (ex-Windsurf)

Set it up

  1. This brain runs code automatically: 1 script. Review Makefile before opening the folder in Claude Code. No step below turns a hook on for you.

    • Makefile: corepack enable; pnpm install --frozen-lockfile
  2. Not scanned by AutoGineerThe author’s README also describes installing it with Docker Compose. Read its install section: AutoGineer did not scan that path. https://github.com/CaviraOSS/LongMemory/blob/aec98ced33a7586a2fcd198a04bc38b5590750c4/README.md#2-run-as-a-service
  3. Not scanned by AutoGineerThe author’s README also describes installing it from a clone of its repository. Read its install section: AutoGineer did not scan that path. https://github.com/CaviraOSS/LongMemory/blob/aec98ced33a7586a2fcd198a04bc38b5590750c4/README.md#2-run-as-a-service

  4. Created by CaviraOSS. Published in CaviraOSS/LongMemory. Licence: Apache License 2.0.

Usage

AutoGineer overview, from the brain’s own files

  • Install as a TypeScript library for in-memory or SQLite-backed agent memory.
  • Deploy as a self-hosted API server using Docker or Docker Compose.
  • Use the CLI to ingest data, manage project context, or perform maintenance tasks.
  • Connect to agent hosts via MCP (Model Context Protocol) for seamless integration.
  • Use the Python SDK to interact with the memory server from Python-based agents.
  • Visualize and manage memory through the provided Next.js dashboard or VS Code extension.
“What was the deployment region in January?”
The agent uses historical recall mode with a specified valid_time to retrieve the correct configuration from that period.
“Prepare the next release.”
The agent retrieves project context, including architecture notes, open tasks, and relevant code facts, to assist with release planning.

Documentation by CaviraOSS

<!-- __ __ ___ / / ____ ____ ____ _/ |/ /__ ____ ___ ____ _______ __ / / / __ \/ __ \/ __ `/ /|_/ / _ \/ __ `__ \/ __ \/ ___/ / / / / /___/ /_/ / / / / /_/ / / / / __/ / / / / / /_/ / / / /_/ / /_____/\____/_/ /_/\__, /_/ /_/\___/_/ /_/ /_/\____/_/ \__, / /____/ /____/ cavira oss (c) 2026 - nullure (c) 2026 ========================================================== file : README.md usage : introduces LongMemory, its architecture, integrations, and deployment options -->

LongMemory

Durable, temporal, governed memory for AI agents. Not just RAG. Not just a vector database. Local-first and self-hosted.

Image: npm Image: PyPI Image: VS Code Image: Container Image: License

Image: LongMemory dashboard

LongMemory is a cognitive memory engine for LLM applications and autonomous agents.

  • Durable local-first storage with SQLite

  • Immutable content, provenance, and temporal truth

  • Strict, historical, associative, grounded, and multilingual recall

  • Explainable evidence selection and token-bounded context

  • Governed project memory, Skills, Chat Memory, LLM-Wiki, and CodeGraph

  • One TypeScript engine across npm, CLI, HTTP, MCP, dashboard, and VS Code

  • Native integrations for agent hosts, automation tools, and Python frameworks

Your model stays stateless. Your application stops being amnesiac.

1. Use It in 10 Seconds

Install as a library
npm install longmemory
import { createMemory } from 'longmemory';

const memory = await createMemory();
await memory.ingest({
    user_id: 'alice',
    text: 'I prefer TypeScript for backend services',
});

const result = await memory.recall({
    text: 'What language does Alice prefer?',
    mode: 'strict',
});

console.log(result);
await memory.close();

No service or external database is required for in-memory use.

For optional evidence-grounded answers with your own model, use the exported answer_from_evidence adapter. It accepts authorized evidence, validates cited excerpts, and makes at most one model call; ordinary recall is unchanged. See docs/answering.md for policies, limits, and integration.

Persist with SQLite
const memory = await createMemory({
    store: 'sqlite',
    db_path: './longmemory.db',
    tenant_id: 'acme',
    user_id: 'alice',
});

Reopening the same database restores nodes, worlds, entities, edges, temporal history, grounding, and lifecycle state.

Install the CLI
npm install --global longmemory
longmemory init
longmemory recall "current project priorities" --mode associative
Call a self-hosted server from Python
pip install longmemory-sdk
from longmemory import LongMemory

memory = LongMemory(
    "http://127.0.0.1:7331",
    api_key="change-me",
    user_id="alice",
)

memory.ingest("I prefer TypeScript")
result = memory.recall("What language do I prefer?", mode="strict")

The Python package is a zero-dependency HTTP client. The Hydrograph engine remains in the self-hosted TypeScript service. See docs/python-sdk.md.

2. Run as a Service

From source
git clone https://github.com/CaviraOSS/LongMemory.git
cd LongMemory
corepack enable
pnpm install --frozen-lockfile
pnpm build
pnpm start

The API listens on http://127.0.0.1:7331 by default.

Docker
docker run --rm \
  -p 7331:7331 \
  -v longmemory-data:/data \
  -e LONGMEMORY_API_KEY=change-me \
  ghcr.io/caviraoss/longmemory:latest
Docker Compose
cp .env.example .env
docker compose up --build -d longmemory

Include the dashboard:

docker compose --profile ui up --build -d

  • API and MCP: http://127.0.0.1:7331

  • Dashboard: http://127.0.0.1:3000

  • Health: http://127.0.0.1:7331/health

3. Why LongMemory

Most systems called memory are retrieval pipelines:

  1. Split text into chunks.

  2. Embed the chunks.

  3. Return the nearest vectors.

That does not establish what was true at a particular time, whether a new fact superseded an old one, which source is authoritative, who may see it, or why a result belongs in context.

LongMemory models those concerns directly:

  • Temporal truth: recorded time and valid time are separate.

  • Immutable memory: content, vectors, hashes, and provenance are not rewritten by recall or decay.

  • Executable graph: typed relationships participate in recall and explanation.

  • Governance: project, tenant, user, team, role, agent, task, and framework scope are enforced.

  • Lifecycle: deterministic decay, explicit reinforcement, consolidation, compression, and reconsolidation.

  • Evidence: recall is bounded by relevance, contradictions, grounding, permissions, and token cost.

See Why.md for the design rationale.

4. Recall Modes

const strict = await memory.recall({
    text: 'What is the current deployment region?',
    mode: 'strict',
});

const historical = await memory.recall({
    text: 'What was the deployment region in January?',
    mode: 'historical',
    valid_time: Date.UTC(2026, 0, 15),
});

const associative = await memory.recall({
    text: 'Incidents related to the payment migration',
    mode: 'associative',
});

const grounded = await memory.recall({
    text: 'Which production endpoint is currently live?',
    mode: 'world_grounded',
});

Strict recall applies temporal, contradiction, contract, confidence, and grounding gates. Historical recall preserves superseded truth. Associative recall follows semantic, lexical, entity, activation, and graph signals. World-grounded recall requires current external evidence.

5. Features

  • Hydrograph memory substrate with immutable nodes, executable edges, worlds, entities, facets, and traces.

  • Temporal reasoning with point-in-time truth, event ordering, supersession, and stale-evidence controls.

  • Multilingual memory with script detection, code switching, transliteration, and cross-language embeddings.

  • Project memory for architecture, decisions, tasks, conventions, failures, handoffs, and code impact.

  • Governed assets for Chat Memory, Skills, LLM-Wiki, and CodeGraph with lifecycle and ACL policy.

  • Session porter for Claude Code, Codex, OpenCode, Gemini CLI, Copilot Chat, Cline, and raw harness logs.

  • Connectors for repositories, local files, Markdown, web content, feeds, cloud documents, and provider APIs.

  • Embeddings through OpenAI-compatible APIs, Gemini, AWS Bedrock, Ollama, Siray, and local HTTP models.

  • Operational surfaces through HTTP, MCP, dashboard, VS Code, n8n, and framework-native MCP clients.

  • Auditable benchmarks for LongMemEval, LoCoMo, BEAM, retrieval quality, temporal behavior, and latency.

6. MCP and Agent Integrations

Start local stdio MCP:

longmemory mcp --db .longmemory/project.db --project current

Expose authenticated Streamable HTTP MCP:

LONGMEMORY_API_KEY=change-me longmemory serve --mcp-http

LongMemory exposes 13 high-level governed tools plus readable resources and agent workflow prompts. Tool arguments cannot override server-bound runtime identity.

Installable integrations include:

  • Claude Code plugin

  • Codex and ChatGPT desktop plugin

  • Gemini CLI extension

  • Agent Plugins 1.0 bundle for OpenClaw and compatible hosts

  • n8n community node usable as an AI Agent tool

  • Cline, Continue, and LibreChat configuration packs

  • Dify and Flowise native MCP setup

  • CrewAI, AutoGen, LangGraph/LangChain, OpenAI Agents SDK, and PydanticAI examples

See integrations/README.md and docs/mcp.md.

7. Temporal and Project Memory

import { createProjectMemory } from 'longmemory';

const projects = await createProjectMemory({
    tenant_id: 'cavira',
    organization_id: 'CaviraOSS',
    project_id: 'longmemory',
    name: 'LongMemory',
    store: 'sqlite',
    db_path: './longmemory.db',
});

await projects.ingestProjectEvent('longmemory', {
    kind: 'decision',
    topic: 'persistence',
    text: 'Use SQLite for local-first persistence',
    source_type: 'architecture_note',
});

const context = await projects.getProjectContext('longmemory', 'prepare the next release');

Project context combines relevant architecture, current decisions, open tasks, failures, code facts, matched Skills, conflicts, and governed asset loadouts under one token budget.

8. CLI

longmemory init
longmemory tui
longmemory status --memories 20 --json
longmemory ingest "Remember the rollback procedure" --type procedure
longmemory recall "What is the rollback procedure?" --mode associative
longmemory memory list --limit 50
longmemory project context "prepare the next release"
longmemory maintenance decay --all
longmemory maintenance reinforce <memory-id>
longmemory skill match "run the release checklist" --agent reviewer
longmemory asset loadout "prepare the release" --agent reviewer --framework codex
longmemory code impact createMemory
longmemory detect
longmemory session discover --from claude-code
longmemory port --from claude-code --to longmemory --all
longmemory session wiki --from gemini-cli --all --name "Project knowledge"
longmemory serve --mcp-http

Finite commands emit stable JSON outside a TTY or when --json is supplied. The session porter reads supported coding-agent stores without modifying them. See docs/cli.md.

9. Dashboard and VS Code

The Next.js dashboard provides health, memory browsing, ingestion, search, project selection, activity, decay, settings, timelines, and memory-aware chat through a same-origin API proxy.

pnpm --dir dashboard build
pnpm --dir dashboard start

The VS Code extension provides an activity-bar browser, status bar, recall, project context, explanation, reinforcement, explicit decay, session import, and reviewed AI-change capture.

pnpm extension:package

The generated package is apps/vscode-extension/longmemory-vscode-0.2.0.vsix.

10. Architecture

graph TB
  INPUT[Events, documents, sessions] --> INGEST[Immutable ingest pipeline]
  INGEST --> GRAPH[(Hydrograph)]
  GRAPH --> STRICT[Strict and historical recall]
  GRAPH --> ASSOC[Associative recall]
  GRAPH --> GROUND[World-grounded recall]
  GRAPH --> PROJECT[Project memory and governed assets]
  GRAPH --> SQLITE[(SQLite)]
  STRICT --> CONTEXT[Explainable bounded context]
  ASSOC --> CONTEXT
  GROUND --> CONTEXT
  PROJECT --> MCP[MCP tools, resources, prompts]
  CONTEXT --> API[Library, CLI, HTTP]
  MCP --> AGENTS[Agents, IDEs, automation]
  API --> UI[Dashboard and VS Code]

Read ARCHITECTURE.md and docs/architecture.md for subsystem details.

11. Deployment Options

PlatformConfigurationWhat it deploys
DockerDockerfileAPI and Streamable HTTP MCP
Docker Composedocker-compose.ymlAPI/MCP plus optional dashboard
Herokuapp.jsonContainerized API/MCP
Railwayrailway.jsonContainerized API/MCP
Renderrender.yamlAPI/MCP with persistent disk
DigitalOcean.do/spec.yamlApp Platform API/MCP service
Vercelvercel.jsonDashboard; configure LONGMEMORY_API_URL
Windowsstart-longmemory.ps1Background local API/MCP process

For hosted API deployments, set LONGMEMORY_API_KEY, mount persistent storage at /data, and terminate TLS at the platform edge. Vercel hosts only the stateless dashboard and requires a separately deployed LongMemory API.

12. Benchmarks

pnpm bench
pnpm bench:ci
pnpm bench:full

The benchmark harness publishes explicit manifests, dataset completion, evidence metrics, answer judgments, temporal categories, latency percentiles, and N/A reasons. Official scorecards fail closed on incomplete datasets or semantic embedding fallback. See benchmarks/README.md.

13. Migration

Import supported SQLite, JSON, or JSONL memory:

longmemory migrate \
  --from ./legacy.db \
  --to ./longmemory.db \
  --report ./migration-report.json

Import coding-agent conversations as governed Chat Memory:

longmemory port --from codex --to longmemory --all

See MIGRATION.md and docs/migration.md.

Legacy package migration:

npm uninstall openmemory-js && npm install longmemory
pip uninstall openmemory-py && pip install longmemory-sdk

openmemory-js@2 and openmemory-py@2 are forwarding bridges for existing installations. New applications should use longmemory and longmemory-sdk directly. PyPI's unrelated longmemory name is owned by another project, so the official distribution is longmemory-sdk while the import remains longmemory.

14. Release and Operations

corepack enable
pnpm install --frozen-lockfile
pnpm release:check
pnpm pack
pnpm extension:package

release:check validates branding, types, integration manifests, the benchmark smoke gate, the root build, extension build, and dashboard production build.

Useful Make targets:

make install
make build
make check
make docker-up
make dashboard

15. Security

LongMemory is local-first, but network deployment still requires explicit controls:

  • Protect API and MCP routes with LONGMEMORY_API_KEY.

  • Restrict allowed origins and terminate TLS at the edge.

  • Keep connector and embedding credentials outside repository files.

  • Treat recalled content as untrusted evidence, not authorization.

  • Preserve server-bound user, project, agent, and framework identity.

Report vulnerabilities privately as described in SECURITY.md.

16. Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md, GOVERNANCE.md, and CODE_OF_CONDUCT.md before contributing.

17. License

LongMemory is licensed under the Apache License 2.0. The separately published n8n community node uses MIT as required by n8n's strict package validator.

Contributors

<!-- readme: contributors -start -->

<table> <tbody> <tr> <td align="center"> <a href="https://github.com/nullure"> <img src="https://avatars.githubusercontent.com/u/81895400?v=4" width="100;" alt="nullure"/> <br /> <sub><b>Morven</b></sub> </a> </td> <td align="center"> <a href="https://github.com/dontbanmeplz"> <img src="https://avatars.githubusercontent.com/u/59851616?v=4" width="100;" alt="dontbanmeplz"/> <br /> <sub><b>Chis</b></sub> </a> </td> <td align="center"> <a href="https://github.com/amihos"> <img src="https://avatars.githubusercontent.com/u/35190548?v=4" width="100;" alt="amihos"/> <br /> <sub><b>Hossein Amirkhalili</b></sub> </a> </td> <td align="center"> <a href="https://github.com/DKB0512"> <img src="https://avatars.githubusercontent.com/u/23116307?v=4" width="100;" alt="DKB0512"/> <br /> <sub><b>DKB</b></sub> </a> </td> <td align="center"> <a href="https://github.com/stevo1403"> <img src="https://avatars.githubusercontent.com/u/34807365?v=4" width="100;" alt="stevo1403"/> <br /> <sub><b>Stephen Adebayo</b></sub> </a> </td> <td align="center"> <a href="https://github.com/mameikagou"> <img src="https://avatars.githubusercontent.com/u/116348059?v=4" width="100;" alt="mameikagou"/> <br /> <sub><b>mrlonely</b></sub> </a> </td> </tr> <tr> <td align="center"> <a href="https://github.com/haosenwang1018"> <img src="https://avatars.githubusercontent.com/u/167664334?v=4" width="100;" alt="haosenwang1018"/> <br /> <sub><b>Sense_wang</b></sub> </a> </td> <td align="center"> <a href="https://github.com/recabasic"> <img src="https://avatars.githubusercontent.com/u/102372274?v=4" width="100;" alt="recabasic"/> <br /> <sub><b>Elvoro</b></sub> </a> </td> <td align="center"> <a href="https://github.com/zfaustk"> <img src="https://avatars.githubusercontent.com/u/4340287?v=4" width="100;" alt="zfaustk"/> <br /> <sub><b>Clio</b></sub> </a> </td> <td align="center"> <a href="https://github.com/suyua9"> <img src="https://avatars.githubusercontent.com/u/273297082?v=4" width="100;" alt="suyua9"/> <br /> <sub><b>suyua9</b></sub> </a> </td> <td align="center"> <a href="https://github.com/vincenzopalazzo"> <img src="https://avatars.githubusercontent.com/u/17150045?v=4" width="100;" alt="vincenzopalazzo"/> <br /> <sub><b>Vincenzo Palazzo</b></sub> </a> </td> <td align="center"> <a href="https://github.com/msris108"> <img src="https://avatars.githubusercontent.com/u/43115330?v=4" width="100;" alt="msris108"/> <br /> <sub><b>Sriram M</b></sub> </a> </td> </tr> <tr> <td align="center"> <a href="https://github.com/fparrav"> <img src="https://avatars.githubusercontent.com/u/9319430?v=4" width="100;" alt="fparrav"/> <br /> <sub><b>Felipe Parra</b></sub> </a> </td> <td align="center"> <a href="https://github.com/DoKoB0512"> <img src="https://avatars.githubusercontent.com/u/123281216?v=4" width="100;" alt="DoKoB0512"/> <br /> <sub><b>DoKoB0512</b></sub> </a> </td> <td align="center"> <a href="https://github.com/whiterabb17"> <img src="https://avatars.githubusercontent.com/u/90134688?v=4" width="100;" alt="whiterabb17"/> <br /> <sub><b>MistrHyde</b></sub> </a> </td> <td align="center"> <a href="https://github.com/octo-patch"> <img src="https://avatars.githubusercontent.com/u/266937838?v=4" width="100;" alt="octo-patch"/> <br /> <sub><b>Octopus</b></sub> </a> </td> <td align="center"> <a href="https://github.com/therexone"> <img src="https://avatars.githubusercontent.com/u/27387245?v=4" width="100;" alt="therexone"/> <br /> <sub><b>Ayush Singh</b></sub> </a> </td> <td align="center"> <a href="https://github.com/kishan0725"> <img src="https://avatars.githubusercontent.com/u/36665975?v=4" width="100;" alt="kishan0725"/> <br /> <sub><b>Kishan Lal</b></sub> </a> </td> </tr> <tr> <td align="center"> <a href="https://github.com/pc-quiknode"> <img src="https://avatars.githubusercontent.com/u/126496711?v=4" width="100;" alt="pc-quiknode"/> <br /> <sub><b>Peter Chung</b></sub> </a> </td> <td align="center"> <a href="https://github.com/muhammad-fiaz"> <img src="https://avatars.githubusercontent.com/u/75434191?v=4" width="100;" alt="muhammad-fiaz"/> <br /> <sub><b>Muhammad Fiaz</b></sub> </a> </td> <td align="center"> <a href="https://github.com/jasonkneen"> <img src="https://avatars.githubusercontent.com/u/502002?v=4" width="100;" alt="jasonkneen"/> <br /> <sub><b>Jason Kneen</b></sub> </a> </td> <td align="center"> <a href="https://github.com/Hchunjun"> <img src="https://avatars.githubusercontent.com/u/11238835?v=4" width="100;" alt="Hchunjun"/> <br /> <sub><b>shan</b></sub> </a> </td> <td align="center"> <a href="https://github.com/naabakkcrypto"> <img src="https://avatars.githubusercontent.com/u/258882739?v=4" width="100;" alt="naabakkcrypto"/> <br /> <sub><b>Naabakk</b></sub> </a> </td> <td align="center"> <a href="https://github.com/mikemikimike"> <img src="https://avatars.githubusercontent.com/u/186855910?v=4" width="100;" alt="mikemikimike"/> <br /> <sub><b>mikemikimike</b></sub> </a> </td> </tr> <tr> <td align="center"> <a href="https://github.com/mgajewskik"> <img src="https://avatars.githubusercontent.com/u/47600161?v=4" width="100;" alt="mgajewskik"/> <br /> <sub><b>Maciej Gajewski</b></sub> </a> </td> <td align="center"> <a href="https://github.com/ajitam"> <img src="https://avatars.githubusercontent.com/u/672661?v=4" width="100;" alt="ajitam"/> <br /> <sub><b>Matija Urh</b></sub> </a> </td> <td align="center"> <a href="https://github.com/machj8968-lab"> <img src="https://avatars.githubusercontent.com/u/274563644?v=4" width="100;" alt="machj8968-lab"/> <br /> <sub><b>machj8968-lab</b></sub> </a> </td> <td align="center"> <a href="https://github.com/buyua9"> <img src="https://avatars.githubusercontent.com/u/274236111?v=4" width="100;" alt="buyua9"/> <br /> <sub><b>buyua9</b></sub> </a> </td> <td align="center"> <a href="https://github.com/aziham"> <img src="https://avatars.githubusercontent.com/u/94932043?v=4" width="100;" alt="aziham"/> <br /> <sub><b>Hamza</b></sub> </a> </td> <td align="center"> <a href="https://github.com/GPT-AGI"> <img src="https://avatars.githubusercontent.com/u/181050363?v=4" width="100;" alt="GPT-AGI"/> <br /> <sub><b>Ting Zhang</b></sub> </a> </td> </tr> <tr> <td align="center"> <a href="https://github.com/RockinPaul"> <img src="https://avatars.githubusercontent.com/u/3741448?v=4" width="100;" alt="RockinPaul"/> <br /> <sub><b>Paul Zarudnev</b></sub> </a> </td> <td align="center"> <a href="https://github.com/oantoshchenko"> <img src="https://avatars.githubusercontent.com/u/1749531?v=4" width="100;" alt="oantoshchenko"/> <br /> <sub><b>Oleksandr Antoshchenko</b></sub> </a> </td> <td align="center"> <a href="https://github.com/lwsinclair"> <img src="https://avatars.githubusercontent.com/u/2829939?v=4" width="100;" alt="lwsinclair"/> <br /> <sub><b>Lawrence Sinclair</b></sub> </a> </td> <td align="center"> <a href="https://github.com/jungdaesuh"> <img src="https://avatars.githubusercontent.com/u/78460559?v=4" width="100;" alt="jungdaesuh"/> <br /> <sub><b>jungdaesuh</b></sub> </a> </td> <td align="center"> <a href="https://github.com/josephgoksu"> <img src="https://avatars.githubusercontent.com/u/6523823?v=4" width="100;" alt="josephgoksu"/> <br /> <sub><b>Joseph Goksu</b></sub> </a> </td> <td align="center"> <a href="https://github.com/EikoocS"> <img src="https://avatars.githubusercontent.com/u/80829508?v=4" width="100;" alt="EikoocS"/> <br /> <sub><b>EikoocS</b></sub> </a> </td> </tr> <tr> <td align="center"> <a href="https://github.com/Dhravya"> <img src="https://avatars.githubusercontent.com/u/63950637?v=4" width="100;" alt="Dhravya"/> <br /> <sub><b>Dhravya Shah</b></sub> </a> </td> <td align="center"> <a href="https://github.com/dflor003"> <img src="https://avatars.githubusercontent.com/u/103017?v=4" width="100;" alt="dflor003"/> <br /> <sub><b>Danil Flores</b></sub> </a> </td> <td align="center"> <a href="https://github.com/DAESA24"> <img src="https://avatars.githubusercontent.com/u/173488786?v=4" width="100;" alt="DAESA24"/> <br /> <sub><b>DAESA24</b></sub> </a> </td> <td align="center"> <a href="https://github.com/ammesonb"> <img src="https://avatars.githubusercontent.com/u/2522710?v=4" width="100;" alt="ammesonb"/> <br /> <sub><b>Brett Ammeson</b></sub> </a> </td> <td align="center"> <a href="https://github.com/auto-pr-bot"> <img src="https://avatars.githubusercontent.com/u/245575329?v=4" width="100;" alt="auto-pr-bot"/> <br /> <sub><b>auto-pr-bot</b></sub> </a> </td> <td align="center"> <a href="https://github.com/anush008"> <img src="https://avatars.githubusercontent.com/u/46051506?v=4" width="100;" alt="anush008"/> <br /> <sub><b>Anush</b></sub> </a> </td> </tr> <tr> <td align="center"> <a href="https://github.com/annelchavez-11594"> <img src="https://avatars.githubusercontent.com/u/271067077?v=4" width="100;" alt="annelchavez-11594"/> <br /> <sub><b>Annel Chavez</b></sub> </a> </td> <td align="center"> <a href="https://github.com/atao2004"> <img src="https://avatars.githubusercontent.com/u/148929819?v=4" width="100;" alt="atao2004"/> <br /> <sub><b>Anna Tao</b></sub> </a> </td> </tr> <tbody> </table> <!-- readme: contributors -end -->

docs/connectors.md

<!-- __ __ ___ / / ____ ____ ____ _/ |/ /__ ____ ___ ____ _______ __ / / / __ \/ __ \/ __ `/ /|_/ / _ \/ __ `__ \/ __ \/ ___/ / / / / /___/ /_/ / / / / /_/ / / / / __/ / / / / / /_/ / / / /_/ / /_____/\____/_/ /_/\__, /_/ /_/\___/_/ /_/ /_/\____/_/ \__, / /____/ /____/ cavira oss (c) 2026 - nullure (c) 2026 ========================================================== file : docs/connectors.md usage : documents LongMemory connectors -->

Hydrograph connectors

Connectors are ingestion sources for LongMemory Hydrograph. They are not vector loaders, generic RAG pipelines, or authorities that silently overwrite memory.

A connector discovers external items, fetches normalized documents or events, and produces a HydrographImportPlan. It never writes memory directly. The shared createMemory facade validates and atomically applies the plan through recursive worlds, entity resolution, contracts, grounding, bitemporal MVCC, executable edge handlers, indexes, sketches, and persistence.

Connector architecture

Connectors contain an internal transport for authentication, listing, fetching, pagination, retries, and file analysis. Transport modules live under src/connectors/transports and are not a second public ingestion API.

The connector layer adds Hydrograph semantics:

  • External identity and versioning

  • Structured worlds, nodes, and executable edges

  • Entity mentions

  • Source permissions and memory contracts

  • Bitemporal validity and update supersession

  • Grounding and citation provenance

  • Cursor and checksum state

  • Deletion history

  • Atomic plan execution

All public external ingestion goes through connectors and sync_connector. The former src/sources subsystem and direct ingest_source path were removed so external data cannot bypass plans, permissions, cursors, or atomic Hydrograph execution.

Connector interface

interface Connector {
  readonly id: string;
  readonly name: string;
  readonly source_type: string;

  connect(config): Promise<void>;
  testConnection(): Promise<boolean>;

  listSources(params?): Promise<SourceRef[]>;
  fetchSource(ref): Promise<SourceDocument | SourceEvent>;
  sync(params): AsyncIterable<ConnectorSyncItem>;

  getCursor(): Promise<SyncCursor | null>;
  setCursor(cursor): Promise<void>;

  mapToHydrograph(item, context): Promise<HydrographImportPlan>;
}

SourceRef identifies a video, repository, issue, pull request, commit, document, page, message, file, or folder without assuming its full content has been fetched.

SourceDocument records source type, external ID, URL, title, author, source timestamps, fetch time, content, metadata, permissions, version, and checksum.

ConnectorSyncItem labels the source transition as created, updated, deleted, unchanged, permission_changed, moved, or renamed.

Import plans

A plan contains only declarative operations:

type HydrographImportPlan = {
  nodes_to_create: planned_node[];
  edges_to_create: planned_edge[];
  worlds_to_create: planned_world[];
  entities_to_resolve: EntityMention[];
  grounding_refs: grounding_ref[];
  contracts: planned_contract[];
  provenance: connector_provenance[];
  deletion_or_supersession_actions: action[];
};

Every planned node must include connector/source identity, external ID, recorded time, version, checksum, permission, contract, provenance, world key, valid/observed time, and grounding source.

memory.applyImportPlan(plan) is the only commit boundary. It:

  1. Snapshots the graph, worlds, resolver, world DB, recall index, sketches, and working memory.

  2. Creates or reuses recursive worlds by connector key.

  3. Resolves every planned entity through the shared resolver.

  4. Ingests every planned node through IngestEngine.

  5. Executes every planned edge through the registered edge handler.

  6. Converts updates and deletions into supersession chains.

  7. Persists nodes, edges, worlds, entities, grounding facts, and sketches in one SQLite transaction.

  8. Restores all in-memory state and rolls back SQLite if any operation fails.

Connectors cannot bypass contracts, bitemporal validity, entity resolution, edge handlers, or persistence integrity.

Mapping rules

  • Connector data defaults to the exocortex.

  • Source-created and source-updated timestamps map to valid and observed time; fetch/application time maps to recorded time.

  • Updates create new immutable node identities and supersedes edges.

  • Deletions create a non-reasoning source-deleted tombstone that supersedes historical nodes. They never erase history by default.

  • Large documents become root/section nodes with contains edges. Markdown headings, code fences, lines, document IDs, versions, timestamps, paths, and citations are preserved.

  • External data requiring freshness sets expires_if_unconfirmed and source_required.

  • Every imported node has connector provenance and a source-backed grounding fact.

  • Stable source checksums prevent unchanged items from being re-imported.

Permissions

Connector permissions are persisted inside the memory contract:

  • public

  • private

  • project

  • team

  • user_only

  • source_restricted

Restricted permissions may name allowed user, team, project, or source IDs. Strict, historical, associative, and world-grounded recall all check permission context before admitting candidates.

const result = await memory.recall({
  text: "deployment plan",
  mode: "strict",
  permission_context: {
    user_id: "user:alice",
    team_ids: ["team:platform"],
    project_ids: ["project:longmemory"],
    source_ids: ["github"],
  },
});

Connector-imported restricted data is denied when permission context is absent. Existing non-connector memories retain their previous behavior because their source_permission is null.

Sync lifecycle

import { createMemory, local_file_connector, sync_connector } from "longmemory";

const memory = await createMemory({
  store: "sqlite",
  db_path: "./longmemory.db",
});

const connector = new local_file_connector({ root: "./docs" });
await connector.connect();

const report = await sync_connector(connector, memory, {
  mode: "incremental",
  retry_failed: 2,
});

Full sync starts with an empty item-state cursor. Incremental sync resumes from getCursor(), compares checksums, and emits only source transitions. The cursor stores checksum, version, resulting node IDs, sync time, deletion state, and source position.

The sync report records discovered event counts, applied plans, node/edge/world IDs, failures, plans, timestamps, and the resulting cursor.

Dry-run maps and reports every change but never calls applyImportPlan and never advances the cursor:

const preview = await sync_connector(connector, memory, {
  mode: "incremental",
  dry_run: true,
});

Failed items are retried independently. A failed plan rolls back its complete transaction without corrupting successful prior items.

Connector catalog

ConnectorStatusHydrograph mapping
GitHubReal starterProject world, repository/docs, issues/comments, PR decisions, commits, files, fixes/modifies/grounds relations
Local foldersReal starterFolder worlds, Markdown/text/JSON documents, paths, modified time, checksums, structural sections
MarkdownReal starterMarkdown-only local discovery, headings, sections, code fences, line citations
WebsitesReal starterPages, structural sections, links, ETags, modified time, freshness contracts
SitemapReal starterSitemap discovery followed by structured page plans
RSS / AtomReal starterFeeds, entries, linked pages, publication times, incremental checksums
YouTubeMetadata/transcript starterVideo world, video metadata, timestamped segments, contains edges, channels, speakers, topics, timestamp URLs
DocsStructural mock starterDocument world, heading sections, versions/checksums, section citations, update supersession

The unified registry contains 50 connector definitions. Configurable remote connectors use the same paginated REST transport and plan lifecycle while allowing tenant URLs, API versions, field mappings, cursors, headers, and token environment variables to be supplied at construction:

  • Code: GitLab, Bitbucket, Azure DevOps, Gitea, Forgejo, Codeberg

  • Cloud storage: Google Drive, OneDrive, SharePoint, Dropbox, Box, Amazon S3

  • Knowledge: Google Docs, Sheets, Slides, Notion, Confluence, Coda, Obsidian Sync gateways

  • Project systems: Jira, Linear, Asana, Trello, monday.com, ClickUp

  • Communication and support: Slack, Discord, Microsoft Teams, Zendesk, Intercom, Freshdesk

  • Data systems: Airtable, PostgreSQL, MySQL, SQLite, MongoDB, Redis, Salesforce, HubSpot

PDF and email remain explicit mock/design connectors until page extraction and mail transport are implemented. They still exercise the plan, permission, cursor, dry-run, and rollback lifecycle without claiming complete remote support. generic_api is a configurable connector rather than a mock.

GitHub mapping

The GitHub connector owns a deep GitHub transport internally:

  • Repository becomes a project world.

  • Directories may become nested path worlds.

  • README and docs become document nodes.

  • Issue comments are child nodes connected with contains.

  • PRs become decision/change nodes and references such as Fixes #12 produce executable support edges.

  • Commits become procedural code-change nodes and modified files receive refers_to edges carrying status/addition/deletion metadata.

  • README grounds a stable project-description node.

  • Commit hashes, branches, file paths, URLs, source timestamps, and API payloads remain in metadata/provenance.

YouTube mapping

YouTube documents carry video metadata and a transcript array. The mapper creates:

  • A video world and root metadata node.

  • One node per transcript segment.

  • contains edges from video to segments.

  • Channel, speaker, and topic entity mentions.

  • Start/duration metadata and timestamp URLs such as ?t=120s.

The starter accepts mock documents so mapping can be developed and tested without network/API-key dependencies. A future remote transport can implement listing/fetching without changing the mapper.

Adding a connector

  1. Implement Connector or extend the transport-backed connector base.

  2. Put reusable remote/local transport under src/connectors/transports; do not expose a parallel ingestion API.

  3. Normalize fetched content into SourceDocument or SourceEvent.

  4. Persist checksum/version state in SyncCursor.

  5. Write a pure mapper returning HydrographImportPlan.

  6. Include permissions, contracts, provenance, grounding, worlds, entities, and temporal fields on every planned node.

  7. Use structural splitting and explicit contains edges for large documents.

  8. Emit supersession/deletion actions rather than mutating or deleting old nodes.

  9. Register a factory with ConnectorRegistry.

  10. Test created, updated, unchanged, deleted, permission, cursor, dry-run, and rollback paths.

Do not call SQLite, vector storage, graph mutation, or memory.ingest from connector implementations. Only the facade plan executor may commit connector data.

512 files · 459 not served here

Advantages

  • Supports temporal truth by separating recorded time from valid time, allowing for historical accuracy. evidence: README.md
  • Provides immutable memory where content and provenance are preserved, preventing accidental overwrites. evidence: README.md
  • Enforces governance policies for projects, teams, and roles to ensure secure and scoped memory access. evidence: README.md

Limitations

  • Requires manual configuration for network deployment, including API key management and TLS termination. evidence: README.md
  • The Python SDK requires a running LongMemory server instance for persistent storage. evidence: README.md

Security

Risk level: Low risk

This brain runs

Install scripts (1)

  • Makefile (make install): corepack enable; pnpm install --frozen-lockfile

MCP servers (2)

  • integrations/claude-code-longmemory/.mcp.json (longmemory): longmemory mcp --project current
  • integrations/gemini-cli-longmemory/gemini-extension.json (longmemory): longmemory mcp --project current
  • Low risk: scripts-present (benchmarks/src/official.ts)
  • Low risk: scripts-present (src/cli/index.ts)
  • Low risk: scripts-present (tools/check-integrations.mjs)

Attribution and licence

Created by
CaviraOSS
First committed by
@nullure
Declared authors
  • CaviraOSS (declared in package.json)
Publisher
Cavira (Community)
Source
CaviraOSS/LongMemory · commit aec98ce
Licence
Apache License 2.0 (files served here)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by CaviraOSS.

Install from source

459 of its files are not served here, so there is no ZIP. CaviraOSS/LongMemory at aec98ce