TekMemo

File-first memory infrastructure for AI apps and agents.

TekMemo is an open-source memory runtime for AI applications. It gives agents, chat apps, coding tools, copilots, workflow systems, and developer platforms a structured way to store, organize, recall, sync, and inspect long-lived context.

TekMemo is built around a simple idea:

AI apps should not depend only on short chat history. They need durable, inspectable, portable memory.

TekMemo provides the open-source packages for that memory layer.

TekMemo Cloud is a separate hosted product that adds team workspaces, hosted sync, MCP access, production observability, billing, usage controls, and managed infrastructure.

What TekMemo solves

Most AI apps lose useful context because memory is scattered across:

chat history
local files
vector databases
logs
prompts
user preferences
project documents
embeddings
tool calls
disconnected app-specific storage

TekMemo gives you a consistent memory layer for these concerns.

It helps you answer questions like:

What should this AI assistant remember?
Where is memory stored?
How is memory recalled?
Which source produced this memory?
Can I inspect or export it?
Can I sync it?
Can another agent or MCP client use it?
Can I evaluate whether recall is working?

Core idea

TekMemo is file-first.

That means memory can be represented as structured, portable files before it is pushed into vector stores, cloud systems, or external tools.

A typical local memory workspace may look like this:

.tekmemo/
├── manifest.json
├── memory/
│   ├── core.md
│   └── notes.md
├── events/
│   ├── memory-events.jsonl
│   └── conversations.jsonl
├── indexes/
│   └── chunks.jsonl
├── graph/
│   ├── nodes.jsonl
│   └── edges.jsonl
└── snapshots/
    └── snapshots.jsonl

Behind the scenes, this makes TekMemo:

portable
inspectable
testable
source-controlled when needed
local-first when needed
cloud-syncable later
easier to debug than hidden memory stores

Sponsor TekMemo

TekMemo is open-source memory infrastructure for AI apps and agents.

If TekMemo helps your work, you can support ongoing development, maintenance, documentation, benchmarks, examples, and new integrations through GitHub Sponsors.

💖 Sponsor TekMemo

Sponsorship helps fund:

package maintenance
documentation
examples
benchmarks
provider integrations
MCP support
memory tooling
open-source issue triage

Repository status

TekMemo is under active development.

The public OSS repository contains the open-source runtime, adapters, docs, examples, and package infrastructure.

The private TekMemo Cloud repository contains hosted cloud functionality such as:

tenant routing
billing
usage enforcement
encrypted BYOK storage
hosted dashboards
internal admin tooling
managed cloud APIs

This repo intentionally does not contain private TekMemo Cloud implementation details.

Packages

Core runtime

Package	Purpose
`tekmemo`	Core memory contracts, records, chunks, source refs, and `.tekmemo/` conventions
`@tekmemo/fs`	Local filesystem-backed memory store
`@tekmemo/agentfs`	AgentFS/Turso AgentFS-backed memory store and sync hooks
`@tekmemo/ai-sdk`	AI SDK tool definitions and memory tool bridge

Embeddings

Package	Purpose
`@tekmemo/voyageai`	Voyage AI embedding adapter
`@tekmemo/openai`	OpenAI embedding adapter

Vector recall

Package	Purpose
`@tekmemo/recall`	Provider-neutral vector recall contracts
`@tekmemo/upstash-vector`	Upstash Vector recall adapter

Reranking

Package	Purpose
`@tekmemo/rerank`	Provider-neutral reranking contracts
`@tekmemo/rerank-voyage`	Voyage reranking adapter

Advanced memory and ingestion

Package	Purpose
`@tekmemo/benchmark-kit`	Benchmark runner and reproducible performance tests
`@repo/test-utils`	Testing utilities for TekMemo packages

Repository structure

tekmemo/
├── apps/
│   ├── docs/
│   └── slides/
│
├── packages/
│   ├── tekmemo/                # Core memory model, types, and utilities
│   ├── ai-sdk/                 # Vercel AI SDK integration
│   ├── fs/                     # Local filesystem adapter
│   ├── agentfs/                # AgentFS adapter
│   ├── openai/                 # OpenAI embedding adapter
│   ├── upstash-vector/         # Upstash Vector adapter
│   ├── voyageai/               # Voyage AI embedding adapter
│   ├── recall/                 # Semantic recall memory
│   ├── rerank/                 # Provider-neutral reranking
│   ├── rerank-voyage/          # Voyage reranking adapter
│   ├── benchmark-kit/          # Benchmarking tools
│   ├── test-utils/             # Testing utilities
│   ├── tsdown-config/          # Shared tsdown config (internal)
│   ├── typescript-config/      # Shared tsconfig bases (internal)
│   └── utils/                  # Shared utility helpers (internal)
│
├── benchmarks/                 # Private benchmark suites and release gates
├── examples/                   # Runnable example projects
│
├── .github/
├── README.md
├── CONTRIBUTING.md
├── SECURITY.md
├── CODE_OF_CONDUCT.md
├── LICENSE
├── package.json
├── pnpm-workspace.yaml
├── turbo.json
└── biome.json

Requirements

Use the following versions or newer:

Node.js >= 22
pnpm >= 9

Recommended:

corepack enable
corepack prepare pnpm@9 --activate

Getting started

Clone the repository:

git clone https://github.com/tekmemo/tekmemo.git
cd tekmemo

Install dependencies:

pnpm install

Build all packages:

pnpm build

Run tests:

pnpm test

Run type checks:

pnpm typecheck

Run lint/checks:

pnpm format-and-lint

Start the docs app:

pnpm --filter docs dev

Start the slides app:

pnpm --filter slides dev

Common commands

pnpm build

Build all packages and apps.

pnpm test

Run all tests.

pnpm typecheck

Run TypeScript checks.

pnpm format-and-lint

Run formatting and lint checks.

pnpm format-and-lint:fix

Auto-fix formatting and lint issues.

Basic usage

Install the core package:

pnpm add tekmemo

Install a local filesystem store:

pnpm add @tekmemo/fs

Install recall packages:

pnpm add @tekmemo/recall @tekmemo/upstash-vector @tekmemo/openai

Example:

import {
	bootstrapMemoryStore,
	readCoreMemory,
	writeCoreMemory,
} from "tekmemo";
import { createNodeFsMemoryStore } from "@tekmemo/fs";

const store = createNodeFsMemoryStore({
	rootDir: ".tekmemo",
});

await bootstrapMemoryStore(store, { projectId: "local-app" });

await writeCoreMemory(
	store,
	"# Core Memory\n\n- TekMemo provides file-first memory for AI apps and agents.\n",
);

const coreMemory = await readCoreMemory(store);

Design principles

TekMemo packages follow these principles:

1. File-first

Memory should be inspectable and portable.

2. Provider-neutral

Core packages should not depend on a specific AI provider, vector database, cloud vendor, or hosted service.

3. Adapter-driven

External systems should be integrated through adapters.

4. BYOK-friendly

Provider adapters should allow users to bring their own keys.

5. Cloud-optional

Open-source packages must work without TekMemo Cloud.

6. Testable with fake clients

Adapters should support fake clients, mock transports, and deterministic tests.

7. Clear package boundaries

Each package should own one concern.

8. Production safety

Packages should handle malformed input, unsafe metadata, cancellation, timeouts, retries, limits, and edge cases.

Package boundary rules

A package should not reach into unrelated concerns.

For example:

tekmemo
  owns core memory contracts and records

@tekmemo/fs
  owns filesystem-backed storage

@tekmemo/recall
  owns provider-neutral recall contracts

@tekmemo/upstash-vector
  owns Upstash Vector adapter

A package should not silently own:

billing
tenancy
usage limits
hosted API keys
dashboards
private cloud deployment logic
admin tooling

Those belong outside this public OSS repo.

Documentation

Public docs are hosted at:

yet to be determined

The docs app lives in:

apps/docs

Slides live in:

apps/slides

Public architecture docs live in:

apps/docs/architecture/

Examples

Examples live in:

examples/

Current runnable examples include:

local-only

Each example should be runnable and should explain what it demonstrates.

Releases

TekMemo uses Changesets for package versioning.

Before publishing, make sure:

pnpm release:check

all pass.

Contributing

Contributions are welcome.

Please read:

CONTRIBUTING

CODE_OF_CONDUCT

SECURITY

before opening issues or pull requests.

Security

Please do not report security issues through public GitHub issues.

See SECURITY.md for responsible disclosure instructions.

License

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
.changeset		.changeset
.github		.github
apps/docs		apps/docs
benchmarks		benchmarks
docs		docs
examples		examples
packages		packages
.gitignore		.gitignore
.npmrc		.npmrc
AGENTS.md		AGENTS.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTORS.md		CONTRIBUTORS.md
GEMINI.md		GEMINI.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
biome.json		biome.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

TekMemo

What TekMemo solves

Core idea

Sponsor TekMemo

Repository status

Packages

Core runtime

Embeddings

Vector recall

Reranking

Advanced memory and ingestion

Repository structure

Requirements

Getting started

Common commands

Basic usage

Design principles

1. File-first

2. Provider-neutral

3. Adapter-driven

4. BYOK-friendly

5. Cloud-optional

6. Testable with fake clients

7. Clear package boundaries

8. Production safety

Package boundary rules

Documentation

Examples

Releases

Contributing

Security

License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages