Trisynapse Memory

Store traces. Recall meaning.

Evidence-first memory for AI agents: ingest many kinds of data, retrieve the useful parts, and answer with citations.

Quickstart · Interfaces · Architecture · API · Operations · Releases

Trisynapse Memory is a local-first memory engine for assistants, agents, and applications. It preserves source evidence in an ordered Trace, builds searchable Recall views, and drills back to the evidence before returning an answer.

Use it when your application needs to remember conversations, documents, code, web pages, tables, images, or structured records—and you need to see where an answer came from.

Why Trisynapse?

[!IMPORTANT] Trisynapse Memory is a pre-1.0 alpha. Its core surfaces are implemented, but APIs and store schemas may still change between minor releases.

Quickstart

1. Install

macOS or Linux:

curl -LsSf https://github.com/shanmukh05/trisynapse-memory/releases/latest/download/install.sh | sh

Windows PowerShell:

irm https://github.com/shanmukh05/trisynapse-memory/releases/latest/download/install.ps1 | iex

Or install from PyPI:

pip install 'trisynapse-memory[all]'

Python 3.11 or newer is required. The first semantic search may download the default local embedding model. Re-run the installer to upgrade; uninstall with uv tool uninstall trisynapse-memory.

2. Store and recall something

trisynapse-memory init
trisynapse-memory add observation "Maya prefers three-bullet weekly updates."
trisynapse-memory query "How should I update Maya?"

No completion API key is required for this path. Without one, Trisynapse returns an extractive answer grounded in the retrieved evidence.

3. Open the interactive terminal

trisynapse-memory

Ask a question as plain text or enter / to browse commands. Suggestions narrow as you type; press Tab or Right Arrow to accept one. Useful commands include /ingest, /sources, /history, /model, /remove, and /check.

Ingest several source types together:

trisynapse-memory --project-id demo ingest \
  ./handbook.pdf ./src https://example.com/guide

trisynapse-memory --project-id demo query \
  "What does the handbook say about releases?"

Each source succeeds or fails independently. The run remains available for inspection and failed-item retries.

Choose how you use it

Python

from trisynapse_memory import MemoryEngine, MemoryNamespace, SourceInput

namespace = MemoryNamespace(user_id="maya", project_id="assistant")
memory = MemoryEngine.from_env(namespace=namespace)

try:
    memory.add("Maya prefers short weekly updates.", episode_id="chat:1")

    memory.ingest_many([
        SourceInput(kind="file", path="./handbook.pdf"),
        SourceInput(kind="directory", path="./src"),
        SourceInput(kind="url", url="https://example.com/guide"),
    ])

    answer = memory.query("How should I write Maya's update?")
    print(answer.answer)
    for citation in answer.citations:
        print(citation.delta_id, citation.locator)
finally:
    memory.close()

Use add() and add_batch() for text that is already normalized. Use ingest() and ingest_many() for files, directories, URLs, repositories, archives, images, and mixed batches.

REST and Memory Studio

trisynapse-memory init
trisynapse-memory serve --studio

Open http://127.0.0.1:8765/studio/. The API token is stored at ~/.trisynapse-memory/store/.api-key; keep it private.

Studio gives you five focused views:

• Memory Viewer — inspect Trace and every Recall helper, then run live retrieval from the current item.
• Sources — browse, preview, ingest, retry, download, and remove sources.
• Queries — watch retrieval run step by step and reopen past workflows.
• Configuration — choose completion, embedding, and retrieval settings.
• Connection — select the server, token, and active namespace.

Health and OpenAPI are available at:

GET http://127.0.0.1:8765/api/v1/health
    http://127.0.0.1:8765/openapi.json

See API and interfaces for request contracts, asynchronous ingestion, SSE query runs, source previews, and graph endpoints.

JavaScript and TypeScript

The TypeScript package is a dependency-free Fetch client for the REST service.

npm install @trisynapse/trisynapse-memory

import { TrisynapseMemory } from "@trisynapse/trisynapse-memory";

const memory = new TrisynapseMemory({
  baseUrl: "http://127.0.0.1:8765",
  apiKey: process.env.TRISYNAPSE_MEMORY_API_KEY,
  namespace: { project_id: "demo", user_id: "maya" },
});

await memory.add("Maya prefers short weekly updates.");
const answer = await memory.query("How should I update Maya?");

console.log(answer.answer);
console.log(answer.citations);

The client also covers mixed ingestion, source previews, query runs, memory graphs, lifecycle operations, model selection, retrieval configuration, and connection checks.

How memory works

flowchart LR
    S["Sources"] --> F["Formation<br/>load and structure"]
    F --> T["Trace<br/>ordered evidence"]
    T --> R["Recall<br/>searchable views"]
    Q["Question"] --> P["Retrieval<br/>plan and route"]
    R --> P
    P --> G["Ground in Trace"]
    G --> A["Answer or abstain<br/>with citations"]

1. Formation loads a source and keeps its useful structure.
2. Trace stores the resulting evidence in order with provenance and lifecycle state.
3. Recall builds replaceable indexes, graph connections, episode views, and compiled claims.
4. Retrieval searches several routes, fuses candidates, and drills back to Trace.
5. Grounding creates an answer with citations or abstains.

Trace is an application data store, not a cryptographic ledger. validate checks SQLite consistency, sequence continuity, evidence references, and retained source blobs. Recall data can be rebuilt; cited evidence always comes from Trace.

Read the architecture guide →

Sources and retrieval

Models are optional

The default setup uses local SentenceTransformers embeddings and no completion provider. Add completion when you want generated answers, richer extraction and Recall, or image understanding.

export ANTHROPIC_API_KEY="your-key"
trisynapse-memory models set completion anthropic claude-sonnet-4-5
trisynapse-memory models test --role completion

Or run the interactive terminal and enter /model to search provider catalogs and select models.

Memory lifecycle

Namespaces isolate memory by project and optionally by user, agent, and session. The same namespace rules apply to Python, CLI, REST, Studio, and TypeScript.

Documentation

Release notes

Published installers and packages are on GitHub Releases. Written notes for each version live in docs/releases/.

Development and benchmarks

pip install -e '.[dev,all]'
pytest -q
ruff check src tests scripts

pnpm install --frozen-lockfile
pnpm --filter @trisynapse/trisynapse-memory check
pnpm --filter @trisynapse/studio test

Benchmark adapters support LoCoMo, LongMemEval, HaluMem, and MemoryDoc. Retrieval mode measures the evidence pipeline without answer-generation calls; end-to-end mode adds provider-backed formation, answering, and judging.

trisynapse-memory bench run locomo \
  --mode retrieval --data-root data/locomo --max-questions 100

trisynapse-memory bench gate --mode retrieval --data-root data

See the benchmark operations guide before treating a result as a release gate.

License

Apache 2.0