fawn-memory

TypeScript toolkit for extracting structured knowledge from text and querying it with natural language. Built on TypeChat, with an in-memory semantic index and a simple REPL for exploration.

Features

• Extract entities, actions, and topics from messages
• Build an in-memory semantic reference index
• Query with natural language or explicit term sets
• Load pre-extracted knowledge from a file
• Export index data for visualization

Install

npm install fawn-memory

Quickstart (library)

import {
  createConversation,
  createMessage,
  createInMemoryStorageProvider
} from "fawn-memory";

const storage = createInMemoryStorageProvider();
const messages = storage.createMessageCollection();

const conversation = await createConversation(messages, "demo", storage);

await conversation.addMessageAsync(
  createMessage("I bought apples and bananas today.", [])
);

const answer = await conversation.query("What did I buy?");
console.log(answer);

REPL mode

Run the entrypoint directly to use the interactive shell:

pnpm dev

Commands inside the REPL:

• @load <path>: load a knowledge file into the index
• @loadindex <path>: load a pre-built index JSON file
• @export [path]: export index data to JSON (default: fawn-index-export.json)
• @lemmatize: add lemmatized forms to the index
• @related [weight] [maxTerms]: expand index with LLM-generated related terms
• @wordnet [weight] [maxTerms]: expand index with WordNet synonyms
• @entity <term>: print entities matching a term
• @action <term>: print actions matching a term
• @topic [term]: print topics matching a term (omit term to print all topics)
• @term <term1> <term2> ...: query by explicit terms
• exit or quit: leave the REPL

There is a sample knowledge file at data/1984ParagraphOutput.txt.

Examples

Memory Service

A web-based memory service with REST API and chat UI.

cd examples/memory
pnpm install
pnpm run dev

Open http://localhost:3000/chat for the interactive UI.

Index Visualizer

Interactive tool for exploring semantic indexes with a relationship graph.

cd tools/index-visualizer
pnpm install
pnpm run dev

Open http://localhost:3001 to load and visualize index data.

Environment

Configure your LLM provider via environment variables:

# Provider selection (default: 'openai')
LLM_PROVIDER=openai   # or 'claude'

# API keys (set the one for your chosen provider)
OPENAI_API_KEY=sk-...        # For OpenAI (also supports legacy OPENAI_SDK_KEY)
ANTHROPIC_API_KEY=sk-ant-... # For Claude

# Optional: Override default model
LLM_MODEL=gpt-4-turbo

dotenv is enabled, so a local .env file works too.

Scripts

• pnpm dev: run the REPL entrypoint with tsx
• pnpm lint: run ESLint
• pnpm build: emit ESM + type declarations to dist/
• pnpm clean: remove the dist/ directory

Development notes

prepublishOnly runs a clean rebuild (pnpm run clean && pnpm run build).