ContextVault v0.1

ContextVault is a local-first, SQLite-backed record store for structured and semi-structured text data, designed to serve as a dependable storage spine inside larger systems.

It is intentionally:

• deterministic
• inspectable
• easy to embed
• boring in the best possible way

There is no cloud, no network layer, and no hidden behavior. You own the database file and everything in it.

---

What it is

ContextVault provides a small, stable API to:

• store records (put)
• retrieve records by ID (get)
• search records by text, tags, source, and time range (search)
• export all records to JSON (export_json)
• import records from JSON (import_json)

All records are stored in a single SQLite database file that you fully control.

---

What it is not

ContextVault is not:

• a vector database
• a semantic search engine
• a document management system
• an orchestration framework
• an AI agent memory system

Those can be built on top of it, but they are intentionally out of scope here.
These non-goals are permanent by design.

---

Installation

Local, editable install:

pip install -e .

Requirements:

• Python 3.10+
• SQLite (bundled with Python)

---

Basic usage

from contextvault import Store

store = Store("data.db")

record_id = store.put( text="example record", metadata={"type": "note"}, tags=["example", "demo"], source="manual" )

record = store.get(record_id) print(record.text)

---

Searching

results = store.search( text="example", tags=["demo"], limit=10 )

for r in results: print(r.id, r.text)

Search behavior:

• text search uses simple SQL LIKE
• tag filtering is exact-match and applied post-query
• results are ordered by creation time (newest first)

---

Export / import

payload = store.export_json()

other_store = Store("other.db") other_store.import_json(payload)

This enables:

• backups
• migrations
• reproducible test fixtures
• offline transfer

---

Data model

Each record contains:

• id (string, caller-supplied or UUID)
• created_at (UTC ISO-8601)
• text (optional string)
• metadata (JSON object)
• tags (list of strings)
• source (optional string)
• external_ref (optional string)

All fields are stored explicitly in SQLite.

---

Stability and scope

ContextVault follows a conservative versioning policy.

• v0.1.x guarantees API stability for:
  • put
  • get
  • search
  • export_json
  • import_json

Future versions may add features, but existing behavior will not change without a major version bump.

---

License

Apache License 2.0.