seeka 0.2.1

Embedded. Extensible. No infrastructure.

seeka is an embedded memory component for AI Agents — like SQLite, it runs inside your process with no server, no setup, and no external dependencies. Drop it into any Agent in minutes.

Memory quality is not hardcoded. seeka's Skills system lets you define exactly how raw input is interpreted and extracted — for any domain, any use case — without touching the core pipeline.

Core Features

Minimalist API

No pipelines, no schemas, no boilerplate:

from seeka import Memory

mem = Memory("./my_memory", llm_uri="openai/gpt-4o-mini", llm_api_key="sk-...")

# Step by step
await mem.note("User prefers dark roast coffee and dislikes anything too sweet.")
await mem.dream()   # LLM refines notes → structured Memos, embeddings stored
results = await mem.recall("coffee preference")

# Or in one call
memos = await mem.remember("User prefers dark roast coffee and dislikes anything too sweet.")

note() is instant — no network call, just persists raw text. dream() does the heavy lifting asynchronously when you're ready. remember() combines both into a single call for simple use cases. recall() is a semantic vector search over everything that's been dreamed.

Automatic Conflict Resolution

When new memories contradict existing ones, seeka detects and removes the outdated entries automatically during dream(). No manual bookkeeping required.

await mem.note("User loves coffee — has a cup every morning.")
await mem.dream()

# Later: user's situation changes
await mem.note("User was diagnosed with acid reflux and has completely stopped drinking coffee.")
await mem.dream()  # ← old coffee memo is removed automatically

results = await mem.recall("coffee")
# Returns only the new "stopped drinking coffee" memo

Extraction Skills — Memory Quality You Control

Memory quality is determined by Skills, not by a fixed pipeline baked into the library. Skills are plain Markdown files that live in your project. seeka ships two built-in skills; you can write your own for any domain, any output format, any extraction rule.

Built-in skills:

from seeka.skills import GENERAL, PREFERENCE

# GENERAL: third-person, resolves relative time refs, preserves complete facts
mem = Memory("./my_memory", ..., skills=[GENERAL])

# PREFERENCE: extracts only explicit and implicit preference signals
# Filters out events and plans — keeps attitude/taste/value judgments only
mem = Memory("./my_memory", ..., skills=[PREFERENCE])

# Combine both
mem = Memory("./my_memory", ..., skills=[GENERAL, PREFERENCE])

Custom skills — a skill is just a directory with a SKILL.md file:

my_project/
  skills/
    meeting_notes/
      SKILL.md        ← name, description, extraction rules
      guidelines.md   ← optional supporting files

---
name: meeting_notes_extraction
description: Extract action items and decisions from meeting notes.
---

Your job is to extract **action items** and **decisions** only.
Ignore open questions, background context, and attendance.

Output action items as: "Owner: task by deadline"
Output decisions as: "Decision: ..."

mem = Memory("./my_memory", ..., skills=["./skills/meeting_notes"])

The LLM sees only the skill's name and description initially. The full body is only revealed after the LLM decides to activate the skill — preventing token waste on irrelevant domains.

Semantic Recall + Reranking

recall() embeds the query and returns the closest Memos by vector similarity. Optionally boost precision with a reranker:

# Basic semantic search
results = await mem.recall("coffee preference", n=5)

# With reranking (local cross-encoder, zero config)
mem = Memory("./my_memory", ..., rerank_uri="cross-encoder/ms-marco-MiniLM-L-6-v2")

# With Cohere reranker
mem = Memory("./my_memory", ...,
    rerank_uri="cohere/rerank-english-v3.0",
    rerank_api_key="...")

# With metadata filter
results = await mem.recall("preference", filter={"user_id": {"$eq": "u42"}})

Namespace Isolation

Separate memory spaces for different users, sessions, or agents — all in the same directory:

alice = Memory("./shared_store", namespace="alice", ...)
bob   = Memory("./shared_store", namespace="bob",   ...)

await alice.note("Alice prefers vegetarian food.")
await bob.note("Bob loves steak.")

# No cross-contamination: each namespace is completely isolated
await alice.recall("food preference")  # returns only Alice's memo

Quick Start

Installation

# Default install — cloud embeddings (OpenAI / Bailian / any OpenAI-compatible)
pip install seeka

# Optional: local embedding & rerank via sentence-transformers (~5 GB,
# pulls torch + transformers; only needed for offline / on-prem usage)
pip install "seeka[local-embed]"

By default seeka has no heavy ML dependencies — vector embeddings go through cloud providers via embedding_uri. Install the local-embed extra only if you actually want to run sentence-transformers / cross-encoder locally.

Zero-config example (no API keys required)

Requires the optional local backend: pip install "seeka[local-embed]".

import asyncio
from seeka import Memory

# No API keys — uses local SentenceTransformer for embedding
mem = Memory("./my_memory")

async def main():
    await mem.note("I love pour-over coffee in the morning.")
    await mem.note("I started learning guitar two weeks ago.")

    memos = await mem.dream()
    for m in memos:
        print(m.content)

    results = await mem.recall("coffee")
    for r in results:
        print(r.content)

asyncio.run(main())

With LLM (structured extraction + conflict resolution)

mem = Memory(
    "./my_memory",
    embedding_uri="openai/text-embedding-3-small",
    embedding_api_key="sk-...",
    llm_uri="openai/gpt-4o-mini",
    llm_api_key="sk-...",
)

See the examples/ directory for runnable demos:

API Reference

Memory(path, **kwargs)

All storage is placed inside path/ — vector store files and a seeka.db SQLite file.

Methods

Memo

The atomic unit of memory returned by dream(), recall(), and memos().

Embedding Providers

LLM (for dream() and conflict resolution)

seeka uses chak for LLM calls. Any model URI supported by chak works:

See chak's provider list for the full 18+ integrations.

If llm_uri is not set, dream() skips LLM processing — each Note is stored as-is as a Memo, and conflict resolution is disabled.

Reranking

Optional, improves recall() precision by re-scoring candidates with a cross-encoder or cloud reranker.

When a reranker is configured, recall(query, n=k) fetches 3k candidates from the vector store, reranks them, and returns the top k.

Extraction Skills

Skills are plain directories committed alongside your project code. The only required file is SKILL.md.

SKILL.md format

---
name: my_skill_name        # snake_case, used as the tool name
description: One-line description shown to the LLM before activation.
---

Full extraction instructions shown to the LLM after it activates the skill.
Write rules, examples, output format — anything the LLM needs.

The LLM receives only name + description on the first pass (like a function signature). The full body is revealed only after the LLM decides this skill is relevant. Supporting files (guidelines, examples, reference data) can be added to the same directory and read on demand by the LLM.

Built-in skills

from seeka.skills import GENERAL, PREFERENCE

# GENERAL — general-purpose memory extraction
# · Converts first-person input to third-person
# · Resolves relative time refs ("yesterday" → absolute date)
# · Disambiguates pronouns and preserves entity names
# · Best for: chat history, factual user information

# PREFERENCE — preference signal extraction
# · Extracts explicit preferences ("I hate milk tea") and implicit ones
#   (repeated behavior → inferred attitude)
# · Filters out events, plans, and neutral facts
# · Best for: personalization, recommendation, user profiling

Custom skill example

See examples/extraction_skills.py for a complete walkthrough including a custom meeting-notes skill.

Storage Backends

seeka supports two embedded vector store backends. Both run inside your process — no server required.

The default is lancedb. To use seekdb, instantiate SeekDB directly from seeka.storage.

Is seeka right for you?

seeka is a good fit if any of these sound like you:

• You don't want to run or maintain a memory service — seeka is a library, not a server.
• You want to customize what gets stored without touching any pipeline code — drop in a Skill and you're done.
• You need per-user or per-agent memory isolation with zero database setup.
• You want memory that self-heals — conflicting facts are resolved automatically, no bookkeeping required.
• You need to ship something in an afternoon, not a sprint.

seeka is not a good fit if you need to index large document collections (RAG), run complex structured queries, or handle bulk-write throughput at scale.