Knowledge Base

Build a self-organizing knowledge base that auto-clusters by meaning and improves over time through consolidation. No manual tagging required.

What you'll build

A knowledge base that organizes itself — facts cluster by semantic similarity, duplicates merge automatically, and knowledge quality improves over time through consolidation sleep cycles.

Prerequisites

Requirement	Details
Account	Starter tier or above (500+ patterns recommended)
API key	From your dashboard
Python	3.9+ with `requests` library
Time	~20 minutes

Why not a traditional knowledge base?

Traditional KB	Engramma KB
Manual categorization	Auto-clusters by meaning
Explicit links between articles	Similarity links form automatically
Search returns text matches	Search returns semantically relevant knowledge
Stale content stays forever	Consolidation prunes and merges outdated facts
Rigid hierarchy	Organic, evolving structure

Steps

Batch-store your knowledge

Import existing documentation, FAQs, or facts into Engramma using the batch-store endpoint. Each fact becomes an independent pattern.

Query with natural language

Ask questions in plain English via the retrieve endpoint. The engine finds semantically related facts across your knowledge base.

Use Active Inference recall

Use the recall endpoint for deeper retrieval that leverages Active Inference to surface contextually relevant patterns.

Trigger consolidation

After bulk import, trigger a consolidation sleep cycle to let the engine merge duplicates and strengthen important patterns.

Monitor and iterate

Check stats to see how your knowledge base is evolving. Add new facts as they emerge.

Complete code

import os
import requests

API_KEY = os.environ["ENGRAMMA_API_KEY"]
BASE_URL = "https://api.engramma-memory.com"
HEADERS = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

# Step 1: Batch-store knowledge
facts = [
    {"text": "Python 3.12 introduced type parameter syntax", "metadata": {"domain": "python", "version": "3.12"}},
    {"text": "Type parameter syntax uses square brackets after class/function names", "metadata": {"domain": "python", "version": "3.12"}},
    {"text": "TypeVar is no longer needed for simple generic functions in 3.12+", "metadata": {"domain": "python", "version": "3.12"}},
    {"text": "Python 3.11 added exception groups and TaskGroups", "metadata": {"domain": "python", "version": "3.11"}},
    {"text": "Exception groups allow multiple exceptions to propagate simultaneously", "metadata": {"domain": "python", "version": "3.11"}},
    {"text": "TaskGroups replace gather() for structured concurrency", "metadata": {"domain": "python", "version": "3.11"}},
    {"text": "Python 3.10 introduced structural pattern matching", "metadata": {"domain": "python", "version": "3.10"}},
    {"text": "Pattern matching uses match/case keywords", "metadata": {"domain": "python", "version": "3.10"}},
    {"text": "Pattern matching supports guards with 'if' clauses", "metadata": {"domain": "python", "version": "3.10"}},
]

resp = requests.post(
    f"{BASE_URL}/v1/memory/text/batch-store",
    headers=HEADERS,
    json={"items": facts}
)
data = resp.json()
print(f"Stored: {data['stored']}, Failed: {data['failed']}")
print(f"Pattern IDs: {data['pattern_ids']}")
print(f"Latency: {data['latency_ms']}ms")

# Step 2: Query with natural language
resp = requests.post(
    f"{BASE_URL}/v1/memory/text/retrieve",
    headers=HEADERS,
    json={"query": "What changed with generics in recent Python?", "top_k": 3}
)
results = resp.json()
for r in results["results"]:
    print(f"  [{r['similarity']:.2f}] {r['text']}")
print(f"Latency: {results['latency_ms']}ms")

# Step 3: Active Inference recall
resp = requests.post(
    f"{BASE_URL}/v1/memory/text/recall",
    headers=HEADERS,
    json={"query": "What replaced TypeVar?", "top_k": 5}
)
recall_data = resp.json()
print(f"\nRecall results:")
for r in recall_data["results"]:
    print(f"  [{r['similarity']:.2f}] {r['text']}")
print(f"Latency: {recall_data['latency_ms']}ms")

# Step 4: Consolidate after bulk import
resp = requests.post(
    f"{BASE_URL}/v1/memory/consolidation/sleep",
    headers=HEADERS,
    json={"mode": "full"}
)
consolidation = resp.json()
print(f"\nConsolidation: {consolidation['status']}")
print(f"Evicted: {consolidation['evicted']}, Strengthened: {consolidation['strengthened']}")
print(f"Duration: {consolidation['duration_ms']}ms")

# Step 5: Check KB stats
resp = requests.get(
    f"{BASE_URL}/v1/memory/text/stats",
    headers=HEADERS
)
stats = resp.json()
print(f"\nKB stats:")
print(f"  Total patterns: {stats['total_patterns']}")
print(f"  Embedding dim: {stats['embedding_dim']}")
print(f"  Storage: {stats['storage_bytes']} bytes")

Keeping knowledge fresh

As your domain evolves, the knowledge base adapts through consolidation:

# Store new or updated information
resp = requests.post(
    f"{BASE_URL}/v1/memory/text/store",
    headers=HEADERS,
    json={
        "text": "Python 3.13 deprecates the old typing.TypeVar for new syntax",
        "metadata": {"domain": "python", "version": "3.13"}
    }
)
print(f"Stored pattern: {resp.json()['pattern_id']}")

# Preview what consolidation would do
resp = requests.get(
    f"{BASE_URL}/v1/memory/consolidation/preview",
    headers=HEADERS
)
preview = resp.json()
print(f"Merge candidates: {preview['merge_candidates']}")
print(f"Estimated patterns after: {preview['estimated_patterns_after']}")

# Merge near-duplicates with a similarity threshold
resp = requests.post(
    f"{BASE_URL}/v1/memory/consolidation/merge-duplicates",
    headers=HEADERS,
    json={"threshold": 0.85}
)
merge = resp.json()
print(f"Merged: {merge['merged']}")
print(f"Patterns: {merge['patterns_before']} → {merge['patterns_after']}")

# After consolidation, retrieval reflects the latest understanding
resp = requests.post(
    f"{BASE_URL}/v1/memory/text/retrieve",
    headers=HEADERS,
    json={"query": "Should I use TypeVar?", "top_k": 3}
)
for r in resp.json()["results"]:
    print(f"  [{r['similarity']:.2f}] {r['text']}")

Scaling tips

Pattern count	Recommendation
< 100	Free tier, no consolidation needed
100-1,000	Consolidate after bulk imports
1,000-10,000	Schedule regular sleep cycles for automatic cleanup
10,000+	Use merge-duplicates with a tuned threshold, monitor storage_bytes via stats

Tip

Use metadata fields to organize large knowledge bases. When storing facts, include domain-specific metadata like {"domain": "python", "version": "3.12"} so you can identify and manage subsets of your knowledge base programmatically.

Info

Unlike traditional knowledge bases that require manual maintenance, Engramma's consolidation sleep cycle automatically merges near-duplicate facts, evicts outdated patterns, and strengthens frequently-retrieved knowledge. Use the preview endpoint to understand what will change before committing.

Next steps

Consolidation — When and how to trigger sleep cycles and merge duplicates
Active Inference Recall — How recall differs from retrieve
API Reference — Full endpoint documentation