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

The v0.0.2 release of Knowledge-and-Memory-Management is exactly what a clean release should look like: no leftover personal paths, no hardcoded /home/you/ dangling in the config, and a clear split between knowledge collection and memory management. If you’ve been following the 0.0.x line, this is the release where the tool finally becomes portable across machines and agents. Here’s what changed and why it matters.

$AGENT_HOME: The Portability Fix

The most visible change in v0.0.2 is the replacement of all absolute personal paths with the $AGENT_HOME environment variable. Previously, the agent’s knowledge store was tied to a specific filesystem layout — a dealbreaker if you’re running agents in containers, across multiple users, or on ephemeral CI runners.

Now, every collection, memory index, and metadata file resolves against $AGENT_HOME. If the variable is unset, the agent falls back to a sensible default (typically ~/.agent), but the contract is explicit: set AGENT_HOME once, and the entire knowledge pyramid moves with it.

Here’s the core path-resolution logic that now underpins everything:

import os
from pathlib import Path

def agent_path(*parts: str) -> Path:
    home = os.environ.get("AGENT_HOME", str(Path.home() / ".agent"))
    base = Path(home)
    # Guard against absolute path injection
    safe_parts = [p.lstrip("/") for p in parts]
    return base.joinpath(*safe_parts)

# Example: web article collection
article_store = agent_path("collections", "web")
video_store = agent_path("collections", "video")
memory_index = agent_path("memory", "index.json")

Enter fullscreen mode Exit fullscreen mode

This single change ripples through the whole codebase. No more path surgery when you switch laptops. No more sed hacks to move a knowledge base between team members. Set AGENT_HOME and go.

Knowledge Collection: Web, Video, Articles

The collection pipeline in v0.0.2 is built around three source types: web pages, video transcripts, and long-form articles. Each source type has its own ingestion path, but they all converge on a common memory format.

• Web: The collector fetches a URL, extracts the main content (stripping nav, footers, and boilerplate), and stores the cleaned text along with the source URL and fetch timestamp. The emphasis is on preserving provenance — every chunk knows where it came from.
• Video: Video collection relies on subtitle/transcript extraction rather than audio transcription. This keeps the pipeline fast and deterministic. If a video has no captions, the collector records the metadata but skips content extraction. No fabricating transcripts.
• Articles: Longer-form content (such as PDFs or full blog posts) goes through a chunking step. The agent splits the article into manageable segments with overlapping boundaries, which later makes retrieval and memory consolidation significantly easier.

All collected items land in <AGENT_HOME>/collections/<source_type>/ with a sidecar JSON metadata file. The directory layout is stable and documented, which means you can inspect what the agent knows just by looking at the filesystem.

Memory Management: Beyond Raw Storage

Storage is not memory. v0.0.2 makes that distinction explicit. The memory management layer is responsible for deduplication, time-based decay, and consolidation.

• Deduplication: If you collect the same article twice, the agent detects the URL hash and updates the existing entry instead of creating a duplicate. Content hashes are computed on the normalized text, not the raw bytes, so minor formatting changes don’t cause duplicate bloat.
• Decay: Memory entries carry a last_accessed timestamp. When the agent retrieves a piece of knowledge, it refreshes that timestamp. A pruning pass removes or archives entries that haven’t been accessed in a configurable window. This isn’t AI magic — it’s a simple LRU policy applied to your knowledge base.
• Consolidation: The agent groups related chunks by source and by topic via a lightweight keyword overlap score. This is not a vector store. It’s a deterministic heuristic that lets the agent say “this new article overlaps with three existing chunks” and merge them into a single memory entry.

The key design choice is that memory management is inspectable. Everything happens on the filesystem, in JSON, with explicit timestamps. You can delete a memory entry with rm, and nothing breaks.

What a Clean Release Means Here

“Clean release” in the v0.0.2 notes isn’t just marketing. It means:

1. No personal artifacts — no /home/alice, no /Users/bob, no Windows drive letters in the codebase.
2. Deterministic layout — given the same AGENT_HOME, you get the same collection structure across machines.
3. Backward-compatible migration — a small utility moves existing collections from the old path format to the new $AGENT_HOME layout on first run.

The release also removes several experimental flags that never matured. If you were relying on those, you’d know — they were undocumented and unstable. Their removal makes the API surface smaller and more honest.

Implications for Agent Workflows

If you’re building multi-agent systems, this release is a solid foundation. Because all knowledge is stored under one portable root, you can:

• Snapshot an agent’s memory by tarring AGENT_HOME.
• Share a knowledge base between agents by pointing both to the same AGENT_HOME on a mounted volume.
• Reset an agent by clearing the memory directory without touching code.

The tradeoff is that this is not a distributed system. It’s a single-host knowledge store with a clean abstraction boundary. For a v0.0.2, that’s the right scope.

Final Thoughts

v0.0.2 doesn’t try to be a vector database or a semantic memory engine. It does three things well: collect knowledge from web, video, and articles; manage that knowledge with deduplication, decay, and consolidation; and stay portable via $AGENT_HOME. The code is boring in the best way — predictable paths, explicit timestamps, and no surprises.

If you’ve been holding off on integrating knowledge management into your agent because the path handling was too fragile, now is the time to re-evaluate. Set AGENT_HOME, run a collection, and inspect the resulting directories. The whole pipeline is transparent. That’s the kind of release I’d rather build on.