Knowledge-and-Memory-Management v0.0.2: Portable Knowledge Collection and Memory Management

v0.0.2 is out, and it's a clean release. That means breaking changes, no migration path from v0.0.1, and a deliberate purge of every absolute, user-specific path baked into the previous build. The headline change: all personal paths are replaced with a portable $AGENT_HOME environment variable. If you've been holding off because the first version hard-coded /home/{you} into its config and index files, now is the time to look again.

What a "Clean Release" Actually Means

For experienced developers, "clean release" is a promise about state, not just features. v0.0.1 shipped with an embedded knowledge base that referenced absolute filesystem paths — my ~/videos/, my ~/articles/, my browser cache. That was fine for local testing and useless for anyone else. v0.0.2 resets that state at the source.

Two things changed:

1. No personal paths baked into the codebase. Any string that started with a real username or machine-specific mount point is gone. The configuration layer, the collection segmenter, and the memory index now resolve everything through $AGENT_HOME.
2. A clean memory index on first run. There is no "upgrade" from v0.0.1. If you ran the prior version, delete its data directory and start fresh. The release notes are explicit: do not carry over old memory blobs. They contain path fragments that will not resolve.

The $AGENT_HOME Contract

The entire release is built around a single environment variable. $AGENT_HOME is the root for all persistent state: raw knowledge collections, processed chunks, and the memory index structure.

The contract is:

• If $AGENT_HOME is set, use it as the absolute base.
• If unset, fall back to $HOME/.agent-home (or the platform equivalent).
• Never store an absolute path in the index — store paths relative to $AGENT_HOME.

That last rule is the critical discipline. The previous version stored absolute paths in the memory index, which made the whole knowledge base non-portable. v0.0.2 enforces relative paths at write time, so you can move the entire agent directory between machines without a rebuild.

The pattern you should use in your integration code:

import os
from pathlib import Path

AGENT_HOME = Path(os.environ.get("AGENT_HOME", Path.home() / ".agent-home")).expanduser()

def resolve_store(*parts: str) -> Path:
    # All storage paths are relative to AGENT_HOME.
    p = AGENT_HOME.joinpath(*parts)
    p.parent.mkdir(parents=True, exist_ok=True)
    return p

# Collections are organized by source type.
web_dir = resolve_store("collections", "web")
video_dir = resolve_store("collections", "video")
articles_dir = resolve_store("collections", "articles")

# The memory index is also relative; no absolute paths allowed.
memory_index = resolve_store("memory", "index.json")

That's it. Set the variable once, and the entire knowledge pipeline — collection, storage, and memory — stays self-contained under one root.

Knowledge Collection: Web, Video, Articles

The collection layer in v0.0.2 accepts three source types: web pages, video transcripts, and long-form articles. Each goes through the same lifecycle:

1. Acquisition — pull the raw content from the source.
2. Normalization — strip navigation chrome, ads, and boilerplate, then convert to a uniform text representation.
3. Chunking — split the normalized text into bounded segments for downstream processing.
4. Indexing — write the chunks and their source metadata into the memory store under $AGENT_HOME.

The chunking step in v0.0.2 is deterministic — same input, same chunks. That matters for memory management. If chunk boundaries shifted between runs, the memory index would need constant revalidation. With deterministic chunking, the index stays stable, and old entries remain valid as long as the source content hasn't changed.

Web collection reads a URL's rendered content, not raw HTML. Video collection works from transcript data rather than audio analysis. Article collection handles multi-page text and sections. The three source types produce the same normalized chunk format, which keeps the memory layer agnostic about where knowledge came from.

Memory Management Without Absolute Paths

Memory management in v0.0.2 is built around the portable root. The memory index stores each chunk with:

• A content hash (for deduplication),
• A relative path to the source chunk file,
• Timestamps for acquisition and last access,
• Source type metadata (web, video, article).

Because paths are relative, you can back up, clone, or migrate the entire knowledge base by copying $AGENT_HOME — nothing inside will point to a machine that no longer exists.

There is also explicit support for clearing memory. Since this is a clean release, the expectation is that you start with an empty store. You can wipe $AGENT_HOME entirely to reset all knowledge, or remove subdirectories (collections/ for raw content, memory/ for the index) to selectively reset.

Migrating to v0.0.2

If you're coming from v0.0.1:

1. Delete the old data directory entirely. Do not copy it over.
2. Set $AGENT_HOME in your environment — shell profile, container, systemd unit, whatever.
3. Re-collect your sources. There's no import path; the reset is intentional.
4. Verify the memory index contains only relative paths. grep '/home/' $AGENT_HOME -r should return nothing.

Final Thoughts

v0.0.2 is a small, focused release. It doesn't add flashy features — it fixes the portability problem at the foundation. The knowledge collection layer handles web, video, and articles cleanly, and the memory management layer now has a proper home that isn't tied to a specific user account. If you've wanted a self-contained knowledge base that travels between machines, set $AGENT_HOME, point it at a portable drive, and let the collection layer do its work.